======================== - TextGUI Text Windows - ======================== Readme For TextGUI v1.0 Last Updated: 8/16/99 1 - What is TextGUI 2 - Using TextGUI 3 - Using CWindow 4 - Using CTextBox 5 - What's Comming Next 6 - "Bugs" in TextGUI 7 - Version History ====================== - 1. What is TextGUI - ====================== TextGUI is a simple window output library which was designed for the MUUDPIC chat program, but now has been released separately. MUUDPIC can handle drawing windows with different background, border, and text colors, and also has a text box routine which handles input. Both the window and textboxes have optional title bars/borders. The TextGUI library is for C++. ==================== - 2. Using TextGUI - ==================== TextGUI was designed to work with a project environment. Include its header file in your code, and include window.cc if you are only using CWindow, or both window.cc and textbox.cc into your project if using CTextBox. You can use TextGUI in a single-file project if you #include the .cc file after the header. A TextGUI window works very similar to cout, by using the insertion operator to display text to it. You can display any simple datatypes, including ints, floats, doubles, shorts, char, and char* null-terminated strings. However, you cannot use the iostream formatting and endl, instead for this you can insert an ostrstream to the window. The CTextBox was designed specifically for non-blocking input. If your program still needs to execute code during an input, traditional cin/scanf will not allow you to do this, plus it will not display correctly into a window or display in colors. CTextBox accepts input from STDIN by using getch(), and you must call Update() on it, which returns true when the user presses ENTER. ==================== - 3. Using CWindow - ==================== REMEMBER: The included wintest.cc includes source code showing practical usage of the library, as well as the MUUDPIC source code which will be released at a time near the release of this library. To use CWindows, you must #include "window.h" and add window.cc to your project, or if a single file project, include the .cc file in the .h. To setup a CWindow, delcare a new variable, and set up its parameters: ------------------------------------------------------------------------------ CWindow win; win.Move(1, 1, 80, 25); /*This statement makes the whole screen a window. The first two parameters are the upper-left corner (screen starts at 1,1), and the next two is the window width and height, respectively. You MUST set the window position before using it!*/ win.SetColors(1, 15, 10); /*This statement changes the colors, from the default 0, 7, 7 standard text attributes. This set will make a blue background with a white border and bright green text in the middle. Since these are the ANSI colors, the color constants will work here also. This statement is optional*/ win.SetName("My Window"); /*This sets the title of the window.*/ win.Draw(); /*This will draw ONLY THE BORDER of the window, and this statement is optional.It does this so you can change the border color without clearing the text inside.*/ win.Clear(); /*This will clear the inside of the window and properly set the background color in the window (since the screen starts black). This statement can be used anytime to clear the text or after changing background colors. It is optional if your background color is black.*/ win << "Hello:\n " << 6 << '+' << 5.5 << " = " << 6+5.5 << '\n'; /*Outputs to the window. Newlines can appear anywhere and unlike the standard conio functions, it will properly end the line, even if the linefeed character is in the middle of the string. You can NOT use endl since that is an ostream object, so you must use '\n' instead*/ ostrstream* temp = new ostrstream; temp << "This is an iostream and can use all the formatting params" << endl; win << temp; /*ostrstream support is for formatting commands like setw() and anything else that works with iostreams only. The temp variable is DELETED when sent to the window!*/ win.Erase(); /*This function simply replaces the window and border area with a black background, erasing the window completely.*/ ------------------------------------------------------------------------------ ===================== - 4. Using CTextBox - ===================== REMEMBER: The included wintest.cc includes source code showing practical usage of the library, as well as the MUUDPIC source code which will be released at a time near the release of this library. NOTE: There is a particular "bug" in CTextBox. It is not recommended to SetMax to a number greater than the total area of the window. This is explained in depth in the "bugs" section. CTextBox requires textbox.h to be included and textbox.cc to be compiled The textbox works similarly in setup as the CWindow. Look at Using CWindow to find out more about some of the functions not commented below. ------------------------------------------------------------------------------ CTextBox input; input.Move(1, 1, 80, 3); //Sets up window position input.SetColors(0, 7, 15); //Grey border, white text input.SetName("Input Box"); //Set window title input.Draw(); input.SetMax(40); /* This limits the max number of characters the user inputs. This function MUST be called otherwise nothing can be inputted (default size is 0); This function also calls reset() to clear the display. Reset() will delete any data in the box as well as clear the background.*/ while (!input.Update()) { //Update returns true if user pressed enter include your loop or wait loop here } *** or *** bool exit = false; while (!exit) { //Main Loop code if (input.Update()) char* entry = input.GetInput(); /* returns a pointer to UNCOPIED data. Feel free to read but it is not safe to write to entry.*/ } input.Erase(); //This also works with CTextBox ------------------------------------------------------------------------------ Another interesting "hack" to CTextBox is creating an input field w/o a border. You can do this by Move()ing the window with parameters, subtracting 1 from x and y, and adding 2 to width, height, which makes a 1 character extra border (since the routines only output to the INSIDE of the window). You can even declare the size even outside screen parameters as long as the INSIDE of the window fits entirely on the screen. Just don't call .Draw() or .Erase() and the window will work perfectly. input.Move(0, 0, 82, 27); //Sets the whole screen to an input field with no //border. ========================== - 5. What's Comming Next - ========================== I do not plan on adding any NEW features to the library unless they are nessacary for the program. If anyone else wants to expand the library, feel free to do so. You could expand the library to allow for on-the-fly movement and overlapping windows easily with a bit of work by using the text block routines to save the text underneath the window. You could also easily add a relative resize() command too, and also expand the library by saving the actual text in the window so resize() will re wrap it. ======================== - 6. "Bugs" in TextGUI - ======================== Why quotes around bugs? Well some of the bugs are not just non-working code, but limitations of conio.h functions. IN GENERAL, if you follow reasonable parameters, like not making a window 2000 characters wide and a title as long as this readme file, it will work perfectly. There is no wordwrapping in windows. This is because cputs() and ScreenPutString() don't do this, and I don't feel like spending hours making my own raw string output library to go with this. However, I was able to get newlines to work successfully not only at the end of strings, but also in the middle, since the string functions only go down one line after \n rather than going down and back to the left (linefeed). That one took awhile -- I split up the strings, outputted, used gotoxy() and did the rest. Setting the input limit larger than the window in a CTextBox can cause some problems. First of all, the input will work perfectly, but if the user scrolls the window down, they will not be able to scroll back up. Input will be completely unhindered, however, so it only looks like you can't erase the text. . . Windows MUST be at least 3 characters high, otherwise the drawing functions, espically Clear()/Reset() will get confused (as there is no space INSIDE the window). At 2 characters, Draw() should work still, however, and at one character . . . get a life a window can't be that small. Setting a title in a window larger than it can handle will only extend the top line. ====================== - 7 - Version History - ====================== 1.0 -- First release