include/CON_console.h

   1 #ifndef CON_console_H
   2 #define CON_console_H
   3
   4 /*! \mainpage
   5
   6 \section intro Introduction
   7 SDL_Console is a console that can be added to any SDL application. It is similar to Quake and other games consoles.
   8 A console is meant to be a very simple way of interacting with a program and executing commands. You can also have
   9 more than one console at a time.
  10
  11 \section docs Documentation
  12 For a detailed description of all functions see \ref CON_console.h. Remark that functions that have the mark "Internal"
  13 are only used internally. There's not much use of calling these functions.
  14
  15 Have Fun!
  16
  17 \author Garett Banuk <mongoose@mongeese.org> (Original Version)
  18 \author Clemens Wacha <reflex-2000@gmx.net> (Version 2.x, Documentation)
  19 \author Boris Lesner <talanthyr@tuxfamily.org> (Package Maintainer)
  20 \author Bradley Bell <btb@icculus.org> (Descent Version)
  21 */
  22
  23
  24 #include "gr.h"
  25 #include "key.h"
  26
  27 //! Cut the buffer line if it becomes longer than this
  28 #define CON_CHARS_PER_LINE   128
  29 //! Cursor blink frequency in ms
  30 #define CON_BLINK_RATE       500
  31 //! Border in pixels from the most left to the first letter
  32 #define CON_CHAR_BORDER      4
  33 //! Spacing in pixels between lines
  34 #define CON_LINE_SPACE       1
  35 //! Default prompt used at the commandline
  36 #define CON_DEFAULT_PROMPT      "]"
  37 //! Scroll this many lines at a time (when pressing PGUP or PGDOWN)
  38 #define CON_LINE_SCROLL 2
  39 //! Indicator showing that you scrolled up the history
  40 #define CON_SCROLL_INDICATOR "^"
  41 //! Cursor shown if we are in insert mode
  42 #define CON_INS_CURSOR "_"
  43 //! Cursor shown if we are in overwrite mode
  44 #define CON_OVR_CURSOR "|"
  45 //! Defines the default hide key (Hide() the console if pressed)
  46 #define CON_DEFAULT_HIDEKEY     KEY_ESC
  47 //! Defines the opening/closing speed
  48 #define CON_OPENCLOSE_SPEED 50
  49
  50 #ifdef __cplusplus
  51 extern "C" {
  52 #endif
  53
  54         enum {
  55             CON_CLOSED, //! The console is closed (and not shown)
  56             CON_CLOSING,        //! The console is still open and visible but closing
  57             CON_OPENING,        //! The console is visible and opening but not yet fully open
  58             CON_OPEN    //! The console is open and visible
  59         };
  60
  61         /*! This is a struct for each consoles data */
  62         typedef struct console_information_td {
  63                 int Visible;                    //! enum that tells which visible state we are in CON_HIDE, CON_SHOW, CON_RAISE, CON_LOWER
  64                 int RaiseOffset;                        //! Offset used when scrolling in the console
  65                 int HideKey;                    //! the key that can hide the console
  66                 char **ConsoleLines;            //! List of all the past lines
  67                 char **CommandLines;            //! List of all the past commands
  68                 int TotalConsoleLines;          //! Total number of lines in the console
  69                 int ConsoleScrollBack;          //! How much the user scrolled back in the console
  70                 int TotalCommands;              //! Number of commands in the Back Commands
  71                 int LineBuffer;                 //! The number of visible lines in the console (autocalculated)
  72                 int VChars;                     //! The number of visible characters in one console line (autocalculated)
  73                 char* Prompt;                   //! Prompt displayed in command line
  74                 char Command[CON_CHARS_PER_LINE];       //! current command in command line = lcommand + rcommand
  75                 char RCommand[CON_CHARS_PER_LINE];      //! left hand side of cursor
  76                 char LCommand[CON_CHARS_PER_LINE];      //! right hand side of cursor
  77                 char VCommand[CON_CHARS_PER_LINE];      //! current visible command line
  78                 int CursorPos;                  //! Current cursor position in CurrentCommand
  79                 int Offset;                     //! CommandOffset (first visible char of command) - if command is too long to fit into console
  80                 int InsMode;                    //! Insert or Overwrite characters?
  81                 grs_canvas *ConsoleSurface;     //! Canvas of the console
  82                 grs_screen *OutputScreen;       //! This is the screen to draw the console to
  83                 grs_bitmap *BackgroundImage;    //! Background image for the console
  84                 grs_bitmap *InputBackground;    //! Dirty rectangle to draw over behind the users background
  85                 int DispX, DispY;               //! The top left x and y coords of the console on the display screen
  86 #if 0
  87                 unsigned char ConsoleAlpha;     //! The consoles alpha level
  88 #endif
  89                 int CommandScrollBack;          //! How much the users scrolled back in the command lines
  90                 void(*CmdFunction)(struct console_information_td *console, char* command);      //! The Function that is executed if you press <Return> in the console
  91                 char*(*TabFunction)(char* command);     //! The Function that is executed if you press <Tab> in the console
  92                 void(*HideFunction)(void); //! The Function that is executed when the console is hidden
  93         }
  94         ConsoleInformation;
  95
  96         /*! Takes keys from the keyboard and inputs them to the console if the console isVisible().
  97                 If the event was not handled (i.e. WM events or unknown ctrl- or alt-sequences)
  98                 the function returns the event for further processing. */
  99         int CON_Events(int event);
 100         /*! Makes the console visible */
 101         void CON_Show(ConsoleInformation *console);
 102         /*! Hides the console */
 103         void CON_Hide(ConsoleInformation *console);
 104         /*! Returns 1 if the console is visible, 0 else */
 105         int CON_isVisible(ConsoleInformation *console);
 106         /*! Internal: Updates visible state. Used in CON_DrawConsole() */
 107         void CON_UpdateOffset(ConsoleInformation* console);
 108         /*! Draws the console to the screen if it isVisible()*/
 109         void CON_DrawConsole(ConsoleInformation *console);
 110         /*! Initializes a new console */
 111         ConsoleInformation *CON_Init(grs_font *Font, grs_screen *DisplayScreen, int lines, int x, int y, int w, int h);
 112         /*! Calls CON_Free */
 113         void CON_Destroy(ConsoleInformation *console);
 114         /*! Frees all the memory loaded by the console */
 115         void CON_Free(ConsoleInformation *console);
 116         /*! printf for the console */
 117         void CON_Out(ConsoleInformation *console, const char *str, ...);
 118 #if 0
 119         /*! Sets the alpha channel of an SDL_Surface to the specified value (0 - transparend,
 120                 255 - opaque). Use this function also for OpenGL. */
 121         void CON_Alpha(ConsoleInformation *console, unsigned char alpha);
 122         /*! Internal: Sets the alpha channel of an SDL_Surface to the specified value.
 123                 Preconditions: the surface in question is RGBA. 0 <= a <= 255, where 0 is transparent and 255 opaque */
 124         void CON_AlphaGL(SDL_Surface *s, int alpha);
 125         /*! Sets a background image for the console */
 126 #endif
 127         int CON_Background(ConsoleInformation *console, grs_bitmap *image);
 128         /*! Sets font info for the console */
 129         void CON_Font(ConsoleInformation *console, grs_font *font, int fg, int bg);
 130         /*! Changes current position of the console */
 131         void CON_Position(ConsoleInformation *console, int x, int y);
 132         /*! Changes the size of the console */
 133         int CON_Resize(ConsoleInformation *console, int x, int y, int w, int h);
 134         /*! Beams a console to another screen surface. Needed if you want to make a Video restart in your program. This
 135                 function first changes the OutputScreen Pointer then calls CON_Resize to adjust the new size. */
 136         int CON_Transfer(ConsoleInformation* console, grs_screen* new_outputscreen, int x, int y, int w, int h);
 137         /*! Give focus to a console. Make it the "topmost" console. This console will receive events
 138                 sent with CON_Events() */
 139         void CON_Topmost(ConsoleInformation *console);
 140         /*! Modify the prompt of the console */
 141         void CON_SetPrompt(ConsoleInformation *console, char* newprompt);
 142         /*! Set the key, that invokes a CON_Hide() after press. default is ESCAPE and you can always hide using
 143                 ESCAPE and the HideKey. compared against event->key.keysym.sym !! */
 144         void CON_SetHideKey(ConsoleInformation *console, int key);
 145         /*! Internal: executes the command typed in at the console (called if you press ENTER)*/
 146         void CON_SetHideFunction(ConsoleInformation *console, void(*HideFunction)(void));
 147         /*! Sets the callback function that is called after a console has been hidden */
 148         void CON_Execute(ConsoleInformation *console, char* command);
 149         /*! Sets the callback function that is called if a command was typed in. The function could look like this:
 150                 void my_command_handler(ConsoleInformation* console, char* command). @param console: the console the command
 151                 came from. @param command: the command string that was typed in. */
 152         void CON_SetExecuteFunction(ConsoleInformation *console, void(*CmdFunction)(ConsoleInformation *console2, char* command));
 153         /*! Sets the callback tabulator completion function. char* my_tabcompletion(char* command). If Tab is
 154                 pressed, the function gets called with the already typed in command. my_tabcompletion then checks if if can
 155                 complete the command or if it should display a list of all matching commands (with CON_Out()). Returns the
 156                 completed command or NULL if no completion was made. */
 157         void CON_SetTabCompletion(ConsoleInformation *console, char*(*TabFunction)(char* command));
 158         /*! Internal: Gets called when TAB was pressed */
 159         void CON_TabCompletion(ConsoleInformation *console);
 160         /*! Internal: makes newline (same as printf("\n") or CON_Out(console, "\n") ) */
 161         void CON_NewLineConsole(ConsoleInformation *console);
 162         /*! Internal: shift command history (the one you can switch with the up/down keys) */
 163         void CON_NewLineCommand(ConsoleInformation *console);
 164         /*! Internal: updates console after resize etc. */
 165         void CON_UpdateConsole(ConsoleInformation *console);
 166
 167
 168         /*! Internal: Default Execute callback */
 169         void Default_CmdFunction(ConsoleInformation *console, char* command);
 170         /*! Internal: Default TabCompletion callback */
 171         char* Default_TabFunction(char* command);
 172         /*! Internal: Default Hide callback */
 173         void Default_HideFunction(void);
 174
 175         /*! Internal: draws the commandline the user is typing in to the screen. called by update? */
 176         void DrawCommandLine();
 177
 178         /*! Internal: Gets called if you press the LEFT key (move cursor left) */
 179         void Cursor_Left(ConsoleInformation *console);
 180         /*! Internal: Gets called if you press the RIGHT key (move cursor right) */
 181         void Cursor_Right(ConsoleInformation *console);
 182         /*! Internal: Gets called if you press the HOME key (move cursor to the beginning
 183         of the line */
 184         void Cursor_Home(ConsoleInformation *console);
 185         /*! Internal: Gets called if you press the END key (move cursor to the end of the line*/
 186         void Cursor_End(ConsoleInformation *console);
 187         /*! Internal: Called if you press DELETE (deletes character under the cursor) */
 188         void Cursor_Del(ConsoleInformation *console);
 189         /*! Internal: Called if you press BACKSPACE (deletes character left of cursor) */
 190         void Cursor_BSpace(ConsoleInformation *console);
 191         /*! Internal: Called if you type in a character (add the char to the command) */
 192         void Cursor_Add(ConsoleInformation *console, int event);
 193
 194         /*! Internal: Called if you press Ctrl-C (deletes the commandline) */
 195         void Clear_Command(ConsoleInformation *console);
 196         /*! Internal: Called if you press Ctrl-L (deletes the History) */
 197         void Clear_History(ConsoleInformation *console);
 198
 199         /*! Internal: Called if you press UP key (switches through recent typed in commands */
 200         void Command_Up(ConsoleInformation *console);
 201         /*! Internal: Called if you press DOWN key (switches through recent typed in commands */
 202         void Command_Down(ConsoleInformation *console);
 203
 204 #ifdef __cplusplus
 205 };
 206 #endif
 207
 208 #endif
 209
 210