Hello Cemetech! I have recently decided to learn a little bit more about the DoorsCS GUI and I have a few questions about it. I used the example provided here: http://dcs.cemetech.net/index.php?title=GUI_API#Example_of_a_GUI_Program

And, I understood that pretty well, but what exactly does GUIRnull do? I know it's a really simple thing but, it confuses me a little bit... Also, in that example, what's the purpose of dat_end being "chained" to winButtons? Is that what closes the program?

One more question, in that example, why does it work even though I never put a 'call CloseGUIStack' in there? Does DoorsCS do this for you? Thanks for the support!

Every "group" in the GUI must start with a Group Master. If you want to put the things in the group inside a small window or a large window, great, but if not, you still need something to "hold" the items in the group: that's what a GUIRNull is.

Yes, Doors CS will close the GUI Stack for you, but it's a very bad idea to depend on that.

Oh, I see, so you couldn't just do 'ld de,myWin', instead, you would have to do 'ld de,null', then, add 'ld a,GUIRnull' after your thing you want to put in your group, then the null label would have '.db $FF' in it, right? Wow, that's a big sentence. Anyway, thanks for explaining this, also, is dat_end just so when the user presses the [X] button on the window, that the program closes? Thanks!

Actually, dat_end is just there so you can calculate the size of the element you're pushing, namely (dat_end-winButtons) bytes. Don't forget the de is the size of the item, hl points to the first byte of the item, and the accumulator 'a' holds the type.

Okay, now I'm a little confused. I thought adding the something like 'dat_end-winButtons' would make it so whenever you press a winButton, it would execute dat_end... how does the size thing work?

In assembly, each label is actually an address. By subtracting the addresses of two different labels, you can tell how many bytes the things in between the labels take up.

Oh wow! That actually makes quite a bit of sense, thanks! So this is basically a way of using "dynamic" memory? So, it would only take up as much memory as it needs to?

Calling that dynamic memory is a bit of abuse of terminology, but yes, more or less correct. When you call PushGUIStack, it copies DE bytes of memory starting at HL from your program into the GUI stack. It also adds three more bytes, two of which track how big that particular item is, and one of which contains the item type (ie, what you passed in A).

Okay, thanks! Also, (this may or may not relate to DoorsCS), what exactly does the .dw instruction do? I see in the comments of the code in the example, it will say something like this: '.dw exitMyProg ;we'll jump to exitMyProg when this button is clicked'

Does that mean that (in the GUI API), the .dw instruction jumps to an address? Because earlier in the example, there was a .dw 0 that you said would jump to address $00. Thanks for all your help!

.dw inserts a word, AKA a 16-bit int, into the current place in the program; it's not an instruction, it's a directive that is executed compile-time.

Oh okay I didn't know what to call it... wait, I'm confused. It inserts a word into the "current place"? What would the current place be? And how does that "jump" to a label?

It's not a jump. When you assemble a program, it takes all the different commands and turns them into numbers. "ret", for example, becomes the hexadecimal number $C9 (or 0xC9, if you prefer). .db 5 inserts a literal byte "5" into the program. .dw $A830 inserts the literal two-byte (16-bit) value $A830 into your program.

So would doing '.dw Label' insert the address of the label in the program? Also, what is the purpose of using .dw in the GUI API example?
Like, what does '.dw exitMyProg' do?

That's exactly what it does. And it gives the Doors CS GUI system an address inside your program that the GUI system can jump to in order to return control to your function, since Doors CS has control while the mouse is running. When you click the mouse, it wants to give control back to your program, so it has to jump to a label in your program.

Oh I see now! So the "jumping" thing is basically what DoorsCS does when you click something? Like, if you had a button, if you wanted it to do something, then the .dw would be used as what happens when you click the button? Also, this is a question about the GUI API information page here: http://dcs.cemetech.net/index.php?title=GUIRPassIn In the format, how would I use that? Like, where would I put all those inputs it says to put in there?

Exactly. Doors CS performs some cleanup on the data it holds onto for running the mouse routine, then jumps back into your program.

In one block, just as for every GUI item that you need to push. Can you clarify your question a bit?

Okay, so you know how you do your PushGUIStacks and stuff at the top of the program, then you have a bunch of labels after that like crashButton: and stuff? Is the stuff in the format the same stuff that goes in the crashButton, etc. labels? If so, how do we know whether it's a .db or .dw?

Hello, again. I figured out the stuff from the post above, and I just have one question. For the GUIRTextLineIn, in the format, there is something that confuses me. 5: Current offset from start of data string [2 bytes] What does that refer to? Will I crash my calculator if I put .db $00 there? Thanks.

I believe that's the current location of the edit cursor. Its value can (probably) be anything when you push the stack entry, but you probably don't want to go changing it once the GUI system has mucked about with it.

Okay, I figured out why the textbox wasn't showing. (super n00b reason) I forgot to add the stack on top -.- But I have a new thing now, what should I put for the 5th byte? I've tried everything, and every time I try to type in the box, my calculator crashes. I tried looking at Document DE 7's code for the GUIRTextMultiline thing, but it had .db 0 in it, and when used with my calculator it crashes it. Please help!