Textbox Example



This example gives you functions which allow you to use a textbox in your programs. This textbox has auto word-wrap, and comes with special features specifically suited for things like dialog in games. You can place the textbox wherever you like on the top screen, and it can be any size (although small sizes won't work too well). This is an upgrade to the "dialogbox" system I have on my game Village, however it doesn't include a selection function yet (for stuff like "yes/no" choices). You can learn some programming techniques from this if you really try hard enough, but its main purpose is to be used (as such, there aren't any insightful comments on how the code works, just comments on how to use it).

The program includes an example run of the textbox, so use that to see the basic textbox methods.

Functions
In order to use the textbox, you'll need to know a few functions. These are:
 * SHOWTEXTBOX: This brings up the textbox. You don't need to call this for every dialog piece; only call it when the dialog box isn't on the screen, but it should be.
 * HIDETEXTBOX: Hides the textbox. You can call this even when the textbox isn't on the screen, but I wouldn't advise it.
 * MAKETEXT: This is the function you'll be using most often. It displays the text stored in the variable SAY$ inside the textbox. It automatically word-wraps, so words shouldn't get cut off in the middle. It also automatically handles text which is too large to fit in one textbox by showing multiple texboxes one after another.
 * WAITTEXT: You'll also be using this function a lot. MAKETEXT does NOT wait for input after text is displayed. If you want the text to linger on the screen until A or B is pressed, use this function.

As described earlier, you place what you want to show in the variable called SAY$. The basic pattern for text is thus:

GOSUB @SHOWTEXTBOX SAY$="TEXT" GOSUB @MAKETEXT GOSUB @WAITTEXT SAY$="MORE TEXT" GOSUB @MAKETEXT GOSUB @WAITTEXT SAY$="EVEN MORE TEXT" GOSUB @MAKETEXT GOSUB @WAITTEXT etc... GOSUB @HIDETEXTBOX

You can make it easier on yourself if you want by creating your own function which calls both MAKETEXT and WAITTEXT. The reason they AREN'T combined is so that you can have text which "interrupts" other text, and so that you can show text and immediately afterwards bring up a menu. Having to press a button after dialog to open a menu that the dialog describes is very annoying.

Customization
There are quite a lot of things to customize, and it's all done through variables which you can change at the top of the program. Here are some of the important ones:


 * TBX: The upper left corner X position of the textbox
 * TBY: The upper left corner Y position of the textbox
 * TBW: The width of the textbox (including edges)
 * TBH: The height of the textbox (including edges)
 * ULC$/URC$/etc.: The characters which make up the edges of the textbox. ULC stands for Upper Left Character, URC stands for Upper Right Character, etc. VC and HC are Vertical and Horizontal Characters, respectively
 * TEXTSPEED: The speed at which the text moves across the box (the default speed, anyway). Larger values are slower, but you can only go up to 9 (really 15, but only if you know hexadecimal notation). If you're not going to be using some of the special textbox features, you can set this to a preferred default value and it should be fine.
 * DEFAULTCOLOR: The color that the edges and default text take on. Using special features, you can change text colors up to the individual letter, but the edges will always take on the "DEFAULTCOLOR" color

Special Text Features
As you'll see in the example (if you run the program), the text speed, color, etc. can be changed as the text is being processed. This is done using special symbols. When a special symbol is seen in the SAY$ variable, the text processor removes it and applies the effect. The special symbols are the arrow characters, the hollow diamond, and the upperscore. If you need to use any of these characters in your text, you can change the symbols using the variables NEWTSPEED$,NEWTLINE$,FORCETWAIT, etc. This is what each special character does:


 * -> (Right arrow): This changes the speed of the text. The effect will last forever until it is changed again. The program expects a single hex digit (0-F) after the arrow to represent the speed of the text. If you don't know hex, just stay in the range of 0-9. NOTE: USING TWO DIGIT VALUES WILL NOT WORK!
 * <- (Left arrow): This changes the color of the text. The effect only lasts for that particular MAKETEXT instance. Once another MAKETEXT is called, the text color changes back to the DEFAULTCOLOR. The program expects a single hex digit (0-F) after the arrow to represent the color. You can use this to distinguish between characters and narration, or to emphasize a particular word. This can be combined with my Text Effects Example to produce a rainbow textbox.
 * V (Down arrow): This starts a new line in the textbox. This is useful for text which looks better on separate lines. This symbol does not require an extra number afterwards.
 * ^ (Up arrow): This starts a new textbox page. It is useful for breaks in text to show a pause. It is equivalent to running two textbox dialog sequences, so it can be used to shorten code. This symbol does not require an extra number afterwards.
 * <> (Hollow diamond): This creates a time pause in the text. It expects a hex digit (0-f) afterwards to represent how long to wait. The number afterwards represents the multiple of 1/6th seconds to wait for. For instance, <>6 means to wait for a full second before continuing the text. This is useful for making dialog flow more naturally.
 * (Upperscore): This allows you to use double quotes in a string. Whenever the program sees this symbol, it will replace it with double quotes when it outputs it to the screen. To see what an upperscore looks like, or to change the symbol which will be converted into a double quote, look near the top of the program for the variable DOUBLEQT$.

PLEASE NOTE: You don't have to use any of these special text features if you're overwhelmed by them or think they're too complicated. The program will work just fine without these, so as long as you don't need these special features, you can ignore them.

Using this in your program
If you want to use this in your program, you'll need to remove the example section. This is as easy as deleting the code starting from the comment which says Example Section and ending with the END function (also, the comments which state Function section). You'll want to keep the ACLS/CLEAR and DIM at the top of your program, along with the constant values (that big section of variables). Finally, you need to put the functions out of the way. Usually, placing them at the bottom works very well. Now that you have it all set up, you can test it with a simple example:

GOSUB @SHOWTEXTBOX SAY$="Does it work? I sure hope so..." GOSUB @MAKETEXT GOSUB @WAITTEXT GOSUB @HIDETEXTBOX

Please see the example section in the program to see how the symbols used correlate to what happens on screen. If you have any questions, please let me know in the comments section!