====== ugBASIC User Manual ====== ===== WINDOWS ===== The ugBASIC programmer expects to be able to produce file selectors, warning boxes and on-screen control panels with a few simple lines of code. The range of windowing command featured in this Chapter allow you to create interactive dialogue boxes by restricting text and graphics operations to selected areas of the current screen. A "window" is simply a rectangular display area, which must first be opened before electronic life can course through it. Your current screen is treated as a window, and opened automatically by the ugBASIC system as window number zero. All other windows have to be opened by you, and you are advised not to re-open window zero or change its size or position. ==== Creating windows ==== The ''WIND OPEN'' will open a window that will be displayed on screen and used for all subsequent text operation until you command otherwise. ''WIND OPEN'' must be qualified by a window number (don't forget that zero has already been allocated to the current screen), followed by the x,y graphic coordinates setting the top left-hand corner of the new window, followed by the width and height of the new window in the number of characters needed. You may also specify an optional border style, with values ranging from 1 to 16. Titles can also be included in window borders, which will be dealt with a little later. Try this example: FOR W = 1 TO 3 WIND OPEN W,(W-1)*96,50,10,15,W PAPER W+3 : PEN W+6 : CLW PRINT "WINDOW";W NEXT The ''WINDOW'' command sets the window number specified as the active window, to be used for all future text operations. There is an automatic saving system for re-drawing the contents of windows, which is explained below. For now, run the following example: FOR W = 1 TO 3 WIND OPEN W,(W-1)*96,50,10,15,W PAPER W+3 : PEN W+6 : CLW PRINT "WINDOW";W NEXT WINDOW 1: PRINT "UGBASIC" WINDOW 3: PRINT "OPEN WINDOWS ON THE WORLD" WINDOW 2: PRINT "LETS ME" The active window is host to the flashing text cursor, unless it has been made invisible with a CURS OFF command. Using ''BORDER'' command you can hange the style and colour of the current window border. Border style numbers range from 1 to ''BORDER COLORS'', and the paper and pen colours can be selected from any available colour index numbers. Any of these parameters can be omitted from the ''BORDER'' instruction as long as the commas are included for any missing values. FOR W = 1 TO 3 WIND OPEN W,(W-1)*96,50,10,15,W PAPER W+3 : PEN W+6 : CLW PRINT "WINDOW";W NEXT WINDOW 1: PRINT "UGBASIC" WINDOW 3: PRINT "OPEN WINDOWS ON THE WORLD" WINDOW 2: PRINT "LETS ME" BORDER 3,2,3 BORDER 2,, By using ''TITLE TOP'' command, you can set a border title at the top of the current window to your chosen title string. This facility will only operate with bordered windows, as follows: CLS WIND OPEN 4,1,1,20,10,1 TITLE TOP "TOP OF THE MORNING" Similarly, the ''TITLE BOTTOM'' instruction assigns a string to the bottom title of the current window, like this: CLS : WIND OPEN 5,75,50,24,15 BORDER 5,6, TITLE BOTTOM "BOTTOM OF THE BARREL" ==== Manipulating windows ==== Before using windows in your programs, you will need to refer to their identification numbers. The ''WINDON'' function returns the value of the current active window. For example: DO CLS : WIND OPEN RND(99)+1,1,1,25,5,1 PRINT "WINDOW NUMBER ";WINDON WAIT KEY LOOP The ''WIND SAVE'' command is extremely valuable for the ugBASIC programmer. Once activated, the command allows you to move your windows anywhere on screen, without corrupting the existing display, by the following method. The contents of the current window is saved as soon as the command is used, and then every time a new window is opened, the contents of the windows underneath get saved automatically. The screen is then re-drawn whenever a window is moved to a new position or closed. As you begin a new program, the current window (the default screen) consumes valuable memory, and this would be wasted if you were to save it as background beneath a small dialogue box. To solve this problem, create a dummy window of the size you need, and place it over the zone you want to save. Now execute your ''WIND SAVE'' command and continue with your program. When this dialogue box is called up, the area beneath it will be saved as part of your dummy window, so it will automatically be restored after your box has been removed. The ''WIND CLOSE'' command deletes the current window. If the ''WIND SAVE'' command has been activated, the deleted window will be replaced by the saved graphics, otherwise the area will be totally erased from the screen. WIND OPEN 1,1,8,35,18,1 : PRINT "Press a key to close this window" WAIT KEY WIND CLOSE The current window can be moved to any acceptable coordinates. Give the new x,y- coordinates after the ''WIND MOVE'' command. Here is an example: WIND SAVE : WIND OPEN 1,0,2,30,10,1 : WIND SAVE FOR M=1 TO 100 PEN RND(PEN COLORS-1) : PAPER RND(PAPER COLORS-1) : PRINT : CENTRE "MAKING MOVIES" WIND MOVE RND(SCREEN WIDTH - 1 )+1, RND( SCREEN HEIGHT - 1)+1 WAIT VBI NEXT The ''SCROLL'' commands are used to control the scrolling of the current window. ''SCROLL OFF'' turns off the scrolling, and whenever the cursor passes beyond the bottom of the window it will reappear from the top. ''SCROLL ON'' starts the scrolling process again, so that a new line is inserted when the cursor tries to pass beyond the bottom of the window. To change the size of the current window, specify the new width and new height in terms of the number of characters using ''WIND SIZE'' command. If ''WIND SAVE'' has been activated, the original contents of the window will be re-drawn by this instruction. If the new window size is smaller than the original, any parts of the original image that lie outside of the new window boundaries will be lost. Alternatively, if the new window is larger, the space around the saved area will be filled with the current paper colour. Please note that the text cursor is always re-set to coordinates 0,0. For example: WIND OPEN 1,16,16,22,10,2 PRINT "I WANT TO BE WIDER!" WIND SAVE WAIT 50 WIND SIZE 30,10 The command ''CLW'' erases the contents of the current window and replaces it with a block of the current ''PAPER'' colour. Like this: CLS : PAPER 4 : WIND OPEN 1,1,1,12,5,1 WINDOW 1 : PRINT "CLEAR OFF" : WAIT 75 PAPER 9 : CLW ==== Creating slider bars ==== One of the standard uses of windows is to create interactive slider bars, like the one at the right-hand side of common Edit Screen. Horizontal slider bars are set up by giving the ''HSLIDER'' command, qualified by the following parameters: the x,y coordinates of the top left-hand corner of the bar (in pixels) followed by the x,y-coordinates of the bottom right-hand corner, then the number of individual units that the slider is divided into. Next, you must specify the position of the active slider box or control button from the left-hand end of the slider, measured in the same sized units as the slider divisions. Finally, give the length of the slider control box in these units. The size of each unit is calculated with this formula: (x2-x1)/number of units Here is an example: E> Hslider 10,10 To 100,20,100,20,5 Hslider 10,50 To 150,100,25,10,10 VSLIDER instruction: draw a vertical slider Vslider x1 ,y1 To x2,y2,units,position,length This works in the same way as Hslider, and sets up vertical slider bars. For a working demonstration, examine the vertical slider in the Editor window, where the number of units into which the slider is divided is set to the number of lines in the current program. Here is a simpler example: E> Vslider 10,10 To 20,100,100,20,5 Vslider 250,0 To 319,199,10,2,6 SET SLIDER instruction: set fill pattern for slider bar Set Slider ink1,paper1,outline1,pattern1,ink2,paper2,outline2,pattern2 SET SLIDER is used to set up the colours and patterns used for your slider bars and their control boxes. 05.07.05 Windows Simply give the index numbers of the ink, paper, outline and pattern to be used for the slider bar, followed by the ink paper, outline and pattern to be used by the slider control box. If negative values are used for either pattern, a sprite image will be commandeered from the sprite bank, allowing even more spectacular effects. Try this example: E> Centre "" : Curs Off Do A1=Rnd(15) : B1=Rnd(15) : C1=Rnd(15) : D1=Rnd(24) A2=Rnd(15) : B2=Rnd(15) : C2=Rnd(15) : D2=Rnd(24) Set Slider Al ,B1,C1,D1,A2,B2,C2,D2 Hslider 10,10 To 300,60,100,20,25 Vslider 10,60 To 20,190,100,20,25 Wait Key Loop Having set up your slider bars, you will want to activate them using the mouse. A simple routine to create working slider bars needs to be included in your main program. As always, remember to test out the ready-made example programs, for a working guide. Displaying a text window To end this Chapter, here is an extremely useful ugBASIC feature that allows the display of a text file directly on screen. Text can be displayed in its own independent screen, it may be scrolled through at will, the display window can be dragged around the screen and there is even a facility to include a title line. READ TEXT$ instruction: display a text window on screen Read Text$ name$ Read Text$ name$,address, length In its simplest form, the READ TEXT$ command reads the text held in a specified filename on disc, for example: X> Read Text$ Fsel$("**") You can move through the displayed text using scroll bars, the arrow icons or via the following key combinations: Key Press Effect [Up Arrow]/[Down Arrow] Move up/down by one line [Shift]+[Up Arrow]/[Down Arrow] Scroll up/down by one page [Ctrl]+[Up Arrow]/[Down Arrow] Jump directly to top/bottom of text [Esc] or [Return] Exit To read some text from an address in memory, there is an alternative version of the READ TEXT$ command. In this case the name$ parameter refers to a title line that will be printed at the top of the viewing window. Address holds the address of the first line of the text to be read. Length specifies the length of the text to be read, in bytes.