Here's a program which demonstrates how to use the BG layer to create a smooth-scrolling textbox. This textbox can be placed anywhere on the screen, and can be any size. Unfortunately, I haven't added word wrap yet due to time constraints, but I'll get to that later. This program will read whatever DATA section you want and print the text to the screen within a box. The program will then enter a scroll loop, where you can use up and down to smoothly scroll through the text (if it's big enough). You can hold L or R to speed up the scrolling. Press A to exit the textbox.
IMPORTANT NOTES![]
This program uses the entire BG layer 0. As such, you cannot use this program at the same time as a BG. For instance, if you were exploring a dungeon and you wanted the scrollbox to pop up, you'd either have to:
- Allow the screen to go black for the textbox
- Temporarily draw the dungeon area on the GRP using GPUTCHR, since you'll most likely be stationary while using the scrollbox (this isn't as hard as it sounds; in fact, it's very easy).
It's also important to note that while the scrollbox is active, it requires the entirety of BGU3 (the last BG page) in order to operate. If you're using this page, you'll have to temporarily move the page somewhere else.
Variables[]
The program was designed so that you can integrate it into your own programs. As such, there are a few variables you can edit in order to fit the box into your needs. For instance, to change the location and dimension of the textbox, you can change the parameters:
- TEXTXS / TEXTXE - The starting and ending X location for the box. TEXTXS must be less than TEXTXE. TEXTXS must be greater than 0 but less than 30. TEXTXE must be greater than 1 but less than 31.
- TEXTYS / TEXTYE - The starting and ending Y location for the box. TEXTYS must be less than TEXTYE. TEXTYS must be greater than 0 but less than 22. TEXTYE must be greater than 1 but less than 23.
To change the buttons for speed scrolling and quitting the box:
- QUITBUTTON - The button (or buttons) which will quit the box. For instance, if you wanted B to quit the box instead, you could set it to 32. If you wanted both A and B to quit the box, you could set it to 48.
- QUICKBUTTON - The button (or buttons) which will cause the box to speed scroll when held. Make sure it's something that's easy to press while scrolling with up and down (like the default: L and R)
You can also change the scroll speed:
- CRUISE - The number of frames it will take to scroll through one line while scrolling regularly. Larger = slower, smaller = faster. You should make this larger than QUICK
- QUICK - The number of frames it will take to scroll through one line while scrolling quickly. Larger = slower, smaller = faster. This really should be quite small, but don't make it 0 (I'm not sure if 1 works).
All 10 of the previous values can be changed at any time. For instance, let's say you want a textbox that fills the whole screen for the intro of a game, but later you want it to only sit at the very bottom. This can be accomplished by setting TEXTXS etc. to fill the screen before you create the scrollbox for the intro, then set them again to fill only the bottom before you create the scrollbox for the rest of the game.
Creating and Destroying the Scrollbox[]
Once you've set up all the variables you'll need, actually using the scrollbox isn't too hard. Here's an example use of the scrollbox:
TEXTBLOCK$="@MYTEXT" GOSUB @SCROLLBOX GOSUB @SCROLLCLEAR
The "TEXTBLOCK$" variable tells the SCROLLBOX function where to find the text data. For instance, @MYTEXT might look like:
@MYTEXT DATA "Here's some text" DATA "And some more" DATA "<END>"
The GOSUB @SCROLLBOX both draws the scrollbox and performs the scrolling loop. Once the user has pressed your QUITBUTTON (which is default A), the function exits. However, it does not clear up the scrollbox. This is so that you can continue to output text to the scrollbox without it flashing between drawn and undrawn. As a result, if you want the scrollbox to go away, you have to call GOSUB @SCROLLCLEAR. That's all you need to create and destroy the scrollbox!
DATA section[]
As stated before, the program expects the text you're putting in the scrollbox to be located in a DATA section. There are a couple of rules for the DATA sections:
- Each string in the DATA is counted as a separate line.
- Make sure each string doesn't go over the edge of the scrollbox (this may change later with word wrap)
- ALWAYS end the DATA section with a single "<END>", otherwise the program will crash. The <END> will NOT show up while scrolling
- The DATA section can contain up to 999 lines. Have fun scrolling!
Integrating into your program[]
You can place the DATA sections wherever you want to. You don't have to call them anything in particular (for instance, you don't have to copy the names "JUNKTEXT" and "OTHERTEXT" used in the examples). The functions that start after the 4 line break should go somewhere where they won't get in the way. I wouldn't suggest putting them at the top of your program unless you want to skip over them. For instance, you can either do this:
"START OF PROGRAM" GOTO @SKIPFUNCTIONS (Place functions here) @SKIPFUNCTIONS "YOUR PROGRAM"
Or, you can do:
"START OF PROGRAM" "YOUR PROGRAM" END (The literal END call) (Place functions here, at the bottom)
Either way, make sure your program doesn't accidentally "fall" into the functions. The only time the functions should be executing is when you call GOSUB @SCROLLWHATEVER. You can get rid of the examples near the top of the program. Make sure that you call "GOSUB @INITCHARACTERS" at some point, otherwise the program won't output text (it'll be random BG tiles). Make sure you set the textbox dimensions, buttons, and speed at some point (you only have to do it once). After that, you're done!
Technical Details[]
Ignore this section if you're not going to be altering the scrollbox!
If you want to try to adapt it to your own needs and you know how to program well, here are some helpful tips:
- TLINEC is the line count of the text.
- TEXTH is the height of the textbox
- TEXTW is the width of the textbox.
- TTOP is the line of text at the top of the scrollbox. This is a very important variable!
- SPEED is the speed at which you want to scroll. This is also very important! If you notice, I set SPEED to be either QUICK or CRUISE depending on the button being pressed, but you can really alter this variable in any way you see fit.
- @SCROLL is the function you want to call to scroll to TTOP with a speed of SPEED. For instance, in the program as it is, I do:
- Set SPEED depending on input
- Update TTOP depending on input
- Fix TTOP if negative or too high (otherwise you'll have empty lines at the bottom)
- Call GOSUB @SCROLL
- The @SCROLL function automatically keeps track of the last time you called it, so it'll assume that you wanted to scroll from the position it was the last time you called it. In this manner, you'll want to call @SCROLL every time the text moves.
- There's an internal system involving FLINE, @FILLLINE, BGOFS, and all that junk. The @SCROLL function hides all this crap. In almost all circumstances, you won't ever need to fiddle with this internal system, even if you're heavily editing the program for a special purpose. Just stick with @SCROLL and TTOP, and you should be fine.
If you need help using this program, please let me know. However, I can't answer questions like "How do I add it to my program", because every program will be different, and I can't add it for you. I hope it works well for you, and I'll try to make a newer version with word wrap at some point!
