Since before Doors CS 6.0 was released in 2007, I have thrown around the idea of including Doors CS-specific BASIC libraries in the shell. In the past I have always ended up rejecting the idea, either because of a lack of space in the app, or more often, because I was concerned about breaking the compability for which I had always striven by making the DCS BASIC header compatible with every other parser. With the addition of a third page to Doors CS, as well as the inclusion of libraries to support XLib, Celtc III, PicArc, and Omnicalc, I have decided that offering additional functionality to BASIC programmers who want it is more important than ensuring wide compatibility of Doors CS program.

Of course, programmers are encouraged to make programs that work with or with the Doors CS libraries; just as real(0) and Det([[1]]) can be used to detect if XLib or Celtic III is installed, Doors CS has a token detection sequence. If no library is installed, det([[42]]) will return 42. If Celtic III is installed, it will return 0. If Doors CS is installed and providing both Celtic III and Doors CS libraries, it will return the value 1337. So far, thirteen main Doors CS libraries have been designed (but please feel free to suggest changes and additions!); all can be accessed using the sum() token. Just as with Celtic's use of the det() token, sum() will continue to function normally if used with a list as the first argument. If the first argument is instead an integer, Doors CS will intercept it, and perform one of the following planned functions:

:: sum(0) - Determine the length of a string of tokens in variable-width font
:: sum(1) - Scan in specified direction along the graphscreen from a starting point until a differently-valued pixel is encountered
:: sum(2) - Copy the homescreen to the graph buffer
:: sum(3) - List all present Pic 1-255 variables, including their archive status
:: sum(4) - Archive or unarchive a Pic 1-255 variable
:: sum(5) - Return version of installed DCSB Lib
:: sum(6) - Simple GUI mouse, taking starting coords and returning ending coords
:: sum(7) - Push item onto GUI stack. 25 subfunctions.
:: sum(8) - Pop item(s) off GUI stack
:: sum(9) - Open GUI stack.
:: sum(10) - Close GUI stack.
:: sum(11) - Render GUI without invoking mouse.
:: sum(12) - Render GUI and invoke mouse.
:: sum(13) - More graphical scrolling Menu() alternative.

All the libraries except sum(7), sum(12), and sum(13) have been implemented. Continue reading at the discuss link for details on these libraries.

The images below demonstrate some of the already-implemented features


(0) Get string width in var-width font: sum(0,{string})
Given a string, find its width if written in variable-width or graphscreen font

(1) Scan for pixel: sum(1,{X},{Y},{dir})
From starting location (X,Y), scan along the LCD until an edge or a pixel UNLIKE the value of the starting pixel is encountered (dark to light, or light to dark). If a screen edge is reached, behaves as if the color changed. (dir: 1=up, 2=down, 3=left, 4=right)

(2) Render homescreen on graphscreen: sum(2,{update})
Draw 128 characters from the homescreen text buffer to the graph buffer. If update=1, also copy to the LCD.

(3) Used pic vars: sum(3)
Returns an N-element list of the numbers of the Pic variables on the calculator (Pic0 = 10). For example, {1,3,10,24} means that Pic 1, Pic 3, Pic 0, and Pic 24 (an extended Pic) are on the calculator.

(4) Arc/Unarc Pic: sum(4,{N},{state})
Unarchive Pic N if state=0, or archive it if state=1. If it is already in the desired state, do nothing.

(5) Return DCS Lib Version: sum(5)
Will return a number indicating what library is being presented to the program, which should indicate what routines are available. This will be set up to return a specific value when Doors CS is _not_ installed, just like real(0).

(6) DCS Mouse: sum(6,{X},{Y})
Run the DCS GUI Mouse starting at {X},{Y}, with acceleration and the user's custom cursor. Will return a list {X,Y,click}, where (X,Y) is the final cursor location, and click = 1 or 2 for left- or right-clicking. This routine will leave the gbuf the way it found it (as well as the GUI stack)

(7) Push GUI Stack: sum(7,{type},{more args...}
This will probably be the most complex type. The following {type} values will take the following arguments:
:: 0 :: GUIRNull: {255} is the only argument. If you wish the item to be transparent, use {254} instead.
:: 1 :: GUIRLargeWin: {icon (10 hex chars)},{title string}
:: 2 :: GUIRSmallWin: {top-left X (0-15)},{top-left Y (0-15)}, {icon (10 hex chars)},{titlestring}
:: 3 :: GUIRFullScreenImg: {# of Pic variable containing img}
:: 4 :: GUIRText: {X},{Y},{0},{string}
:: 5 :: GUIRWinButtons: {128 + 64 + 32}. 128 if a minimize button should be shown, 64 if a maximize button should be shown, 32 if a close button should be shown. eg, 160 for just minimize and close. 32 for just close. 64 for just maximize. 192 for all three.
:: 6 :: GUIRWrappedText: {X},{Y},{width in pixels},{0},{string}
:: 7 :: GUIRButtonText: {X},{Y},{string}
:: 8 :: GUIRButtonImg: {X},{Y},{image width in bytes},{button width in pixels},{image hex, 10*image width characters long}
:: 9 :: GUIRTextLineIn: {X},{Y},{width in pixels},{maximum chars},{initial string}
:: 10 :: GUIRRadio: {X},{Y},{group ID},{0 or 1},{string}
:: 11 :: GUIRCheckBox: {X},{Y},{group ID},{0 or 1},{string}
:: 12 :: GUIRByteInt: {X},{Y},{initial},{min},{max}
:: 13 :: GUIRWordInt: {X},{Y},{initial},{min},{max}
:: 14 :: GUIRHotspot: {X},{Y},{width},{height}
:: 15 :: GUIRTextMultiline: {X},{Y},{rows},{px width},{string}
:: 16 :: GUIRSprite: {X},{Y},{height (8 px wide is assumed)},{2*height hex chars}
:: 17 :: GUIRLargeSprite: {X},{Y},{width in bytes},{height in px},{height*width*2 hex chars}
:: 18 :: GUIRPassIn: {X},{Y},{width in px},{max chars},{initial string}
:: 19 :: GUIRScrollVert: {X},{Y},{height in px},{ID},{inc/dec per click}, {min val},{max val},{current}
:: 20 :: GUIRScrollHoriz: {X},{Y},{width in px},{ID},{inc/dec per click}, {min val},{max val},{current}
:: 21 :: GUIRBorder: {X},{Y},{width},{height},{color}
:: 22 :: GUIRRect: {X},{Y},{width},{height},{color}
:: 23 :: THERE IS NO 23
:: 24 :: GUIRMouseCursor: {X1*256+Y1},{X2*256+Y2},{16-char mask},{16-char cursor}

(8) Pop GUI Stack Items: sum(8,{number to pop})
Self-explanatory

(9) Open GUI Stack: sum(9)
Initialize the GUI Stack

(10) Close GUI Stack: sum(10)
Shut down the GUI stack

(11) Render GUI Stack: token(11)
Just render, don't call the mouse

(12) GUIMouse: token(12)
Render, and start the mouse. This will return a whole mass of stuff, including a list of {X,Y,num}, where num is the index of the element that made mouse execution stop, and a String (maybe Str0?) that contains packed outputs from text input boxes, number input boxes, radio buttons, and checkboxes.

(13) Scrolling menu: token(13,"TITLE","box-delimited item list","packed label list")
Because of certain limitations in passing strings to parserhook'd functions, the list of items is a single string delimited by the plot box character. The list of labels for Goto'ing are packed, such as one-character labels are represented as [space][char]. For a three-item menu that has the option to Goto Lbl AA, Lbl H, or label QQ, the list would look like: "AA HQQ". This routine creates a small window with the menu items and a scrollbar, allows scrolling, and does the requested Goto. It however does NOT invoke the GUI Mouse.

I don't get it. There is, however, no rule 6.

23 is, in normal DCS GUI parlance, the GUIRCustom item, allowing the program to specify the address of a routine to call that will render something custom into the GUI. Unfortunately, I don't feel like figuring out a way to somehow make that work with BASIC programs, so I'm omitting it for now. As they say, you can complete 90% of features with 10% effort, then it takes 90% effort to complete the remaining 10% of features.

*bump* sum(7,0, sum(7,1, sum(7,2, and sum(7,5 completed. The screenshot below demonstrates the latter three items.

To make a custom control, could the user simply pass in a label name, and you could call that label, with a parser hook on the Return command?

Yeah, I thought about that, or having the program pass the name of a program to call for the custom routine, but that's something for me to worry about after I get the rest of the standard stuff finished. I'm currently working on issues with sum(7,4) through sum(7,9) as well as sum(12).

After a bit of awkward wrangling with some omissions on my part since yesterday evening, I also got sum(7,3), sum(7,4), sum(7,5), sum(7,6), sum(7,7), sum(7,, and sum(7,9) working, respectively GUIRFullScreenImage, GUIRText, GUIRWrappedText, GUIRButtonText, GUIRButtonImg, and GUIRTextLineIn. The screenshot below demonstrates everything except GUIRFullScreenImage. Here's a copy of the source below, just so you can see how easy it is to do stuff like this:


Code:

It would also be nice if we could have custom-sized windows.

Taken under advisement. I think it's a good idea, but I want to make sure I get everything else that's already supported in Doors CS settled before I undertake that. The hardest part would be the GUIRWinButtons, since it would be a little more complicated to find the right edge of the window in nonstandard window sizes.

Sum(7,10) and sum(7,11) finished; I was actually able to use the exact same routine for both of them, huzzah. The following screenshot shows a single radio button group containing three radio buttons, and a pair of independent checkboxes.

Here's sum(7,12) and sum(7,13), all ready to go. Note also that fragments of sum(12), the full GUIMouse, are complete, although it for some reason disables the parserhook (you can see that at the end of this screenie). This shows a GUIRByteInt that can go from 6 to 137, and a GUIRWordInt that can go from 1335 to 1339.

Sum(7,14) and sum(15): GUIRHotspot and GUIRTextMultiline. During testing I noticed that there's still a bug or two in cursor movement in small textboxes; I'll have to look back at this again.

Would it be asking to much to request optional word-wrapping?

I say optional because on smaller text boxes you might not want it. But for larger multi-line text boxes, it'd be a very nice feature


Also, I suggested in the other topic about custom program-defined mouse-sprites. Hoping I can get some people to hop on board with me on the idea? I would love to see it once you have the time to implement it after 6.7, Kerm

It might be quite painful to implement, but I'll take it up consideration. A higher-priority task for multiline text input is using the edit buffer routines to save lots of insertmem/delmem'ing.

I'll think about it, it seems like a good idea if a lot of people would be interested in using it (and therefore making it worth my while).

SO! All of the sum(7) routines are completed! Before 6.7, I need to finish making sum(12), and in theory I should make sum(13), although I don't think I'll have time for that. The screenshot below shows off many of the features between sum(7,16) and sum(7,24), including password input, scrollbars, custom cursors, small and large sprites, and filled and outline rectangles.

Awesome!

Thanks, SilverShadow. sum(12) is progressing smoothly, and is more than halfway done at this point. The main thing I have left (and am slowly working on between other IRL commitments) is generating a string containing the values of the checkboxes, radio buttons, text input boxes, and number input boxes. Do you guys think that sum(12) should take another argument 0-9 specifying which string to store to? Or always use a single string?

Always use a single string.

Sorry, let me clarify that: should I pack everything into a single string, and have it be the same string in every program? Or pack everything into a single string, and let the program specify which string it's packed into?

I think the user should be able to specify the string.

Excellent, I agree. Therefore the sum(12) syntax will be sum(12,{mouse initial X},{mouse initial Y},{string 1-10 = Str1 through Str9 and Str0}). It will return a list containing {final X, final Y, click type (left=1, right=2), triggered hotspot}, and also store packed data to the specified string.