[Tutorial] The Window. Module

[Delos]

A WINDOW. TUTORIAL

So you've been plugging away at your programme for a while now, and you think to yourself, 'Now, if only I could open some new windows. They'd be great for dialogue boxes, showing pictures, and just randomly creating pop-up madness!' Well, never fear, for through the limited power of Turing and the unlimited power of the written (or this case typed) word you shall be introduced to the world of Window.().

Why Window.()?

Why would you want to create additional windows in the first place? Why not set your usual window to full screen and work around that? Well, for starters, Turing 4x doesn't have a real full screen option - only the option to have your dimensions as large as the current resolution.
Otherwise, it's all a matter of taste. Some people enjoy having additional windows to serve input or informational purposes since you can choose which window to keep active and which to inactivate. This can be useful.

Window.() Routines

Window.Open (setUpString : string) : int
Window.Close (winID : int)
Window.Select (winID : int)
Window.GetSelect () : int
Window.SetActive (winID : int)
Window.GetActive () : int
Window.GetPosition (winID, var x, y : int) : int
Window.SetPosition (winID, x, y : int) : int
Window.Hide (winID)
Window.Show (winID)
Window.Set (winID : int, setUpString)
Window.Update (winID)

Basic Glassware

To begin with, we need to come to terms with Window ID numbers. Call them what you like, these are integral variables through which Turing handles windows. Much like file streams that are used in the File.() module.

Turing:

put "Hello World" put Window.GetActive

The output from this piece of code will be the said text, as well as the number -1. What is the significance of this? Well, Window.GetActive() checks the currently active window and returns its ID number. What does active mean? To be active means to be foremost in the screen, to be the focus of attention. A subtle difference is to be Selected as opposed to being Active. We'll get to that shortly.
So why was the number -1? '-1' is the ID number associated with the Main Run Window of Turing. If you have not explicitly setup your own Windows ahead of time, this is the one that gets created for you.
As a side note, there are actually three windows created when a programme is run, but two of them remain hidden by default.

Turing:

put "Hello World" put Window.GetSelect

Again, we get the same output. The difference is, as said before, quite subtle. A window that is selected is the one to which output is to be sent and input to be received. It needn't be the active window though. What on Earth do I mean? We'll get to that as soon as we've introduced a few more commands, so keep it in mind.

Turing:

var winID1 : int winID1 := Window.Open ("graphics:300;200;nobuttonbar;position:top;right") put "I am an Open window with ID ", Window.GetActive, "."

Here we have Opened a new Window. Does any of this look familiar? Well, if you've ever played with setscreen or its View.() counterpart, you'll feel right at home. We create a new integral variable (winID1) and then assign a window to it. You may notice during our trip around Window-land that some routines are procedural while others are functional. I'll leave it up to you to figure out why.

Time to get back to our dilemma or differentiating between Active and Selected windows.

Turing:

var winID1 : int var winID2 : int winID1 := Window.Open ("graphics:300;200;nobuttonbar;position:top;right") winID2 := Window.Open ("graphics:300;200;nobuttonbar;position:top;left") Window.Select (winID1) put "I am an Open window with ID ", Window.GetSelect, "." Window.Select (winID2) put "I am an Open window with ID ", Window.GetSelect, "." Window.SetActive (winID1) delay (300) put "I am now ACTIVE!" delay (300) Window.Select (winID2) for i : 1 .. 5     put "But I am SELECTED!"     delay (200) end for put "Terminated!"

Study the output for a bit. What do you think would happen if you added an input command, such as get to that stew? Try it out: create a string variable and get it inside the for loop. Don't continue with this until your altered programme terminates.
Surprised? You shouldn't be.

Since we've Opened a window, it follows that we should be able to Close a window. This is where Window.Close() comes into play. Let's try:

Turing:

put "Hello World" Window.Close (Window.GetActive)

zOMG! NOO00Ooo! An Error. What ever will we do?
This particular error was very constructive and expansive to our knowledge. To safely Close a window, we have to have Opened it in the first place! This may seem completely logical to you right now, but many a problem have been caused due to this technicality. As a side note, this kind of thing sometimes pops up whilst using GUI.() commands.
To see this command working as it should, add a few lines to the example above demonstrating Selection and Activation. When the programme terminates, put a bit of a delay (so you can marvel at the output), then close both windows. Does it matter which one is Selected or Active at the time?

And that, one and all, are the basics of Window().: .Open, .Close, .Select, .GetSelect, .GetActive, .SetActive.

Up next are some more advanced routines that assume at least a basic knowledge of Window.(), so read on"¦

Stained Glass: Advanced Window.()

Sometimes, a particular window needs to be sent away for a little while for various reasons. Perhaps it was misbehaving. Perhaps it needed a make-over. Perhaps you just had too darn many windows open at once! What ever the case, Hide and Show are the way to go.

Turing:

var winID1 : int var winID2 : int winID1 := Window.Open ("graphics:300;200;nobuttonbar;position:top;right") winID2 := Window.Open ("graphics:300;200;nobuttonbar;position:top;left") Window.Select (winID1) delay (400) Window.Hide (winID1) put "While you were out..." delay (400) Window.Show (winID1)

Important! A hidden window may still have output sent to it! But, keyboard input is not allowed. Try it out. Create a string variable and place a get command after "While you were out"¦". A little error will pop up. Mouse input, however, can still be registered.

Quite often, one needs to know the whereabouts and status of a particular window. GetPosition() will accomplish this for you.

Turing:

var winID1 : int var winID2 : int var x1, y1, x2, y2 : int winID1 := Window.Open ("graphics:350;200;nobuttonbar;position:top;right") winID2 := Window.Open ("graphics:350;200;nobuttonbar;position:top;left") Window.GetPosition (winID1, x1, y1) Window.GetPosition (winID2, x2, y2) Window.Select (winID1) put "I am winID", Window.GetSelect, " and I am located at (", x1, ",", y1, ")." put "My dimensions are ", View.maxx, " x ", View.maxy, "." Window.Select (winID2) put "I am winID", Window.GetSelect, " and I am located at (", x2, ",", y2, ")." put "My dimensions are ", View.maxx, " x ", View.maxy, "."

Notice that GetPosition was a procedure, and that it required variables to assign values. As a bit of an extra, this particular programme also returns Window dimensions, though this particular function is grouped under View.() routines as opposed to Window.(). One could always speculate as to why, though it wouldn't particularly matter. Again, play around with changing Select to SetActive to see if anything changes. If it does, why? If not, why?

Now that you know all you need to know about a window, I'm sure you feel the urge to change them somehow. I mean, if you're going to create something, you should at least have the power to alter it to some extent. It so happens that you can alter these to the same extent as to which they were created.

Turing:

var winID1 : int var winID2 : int var x1, y1, x2, y2 : int winID1 := Window.Open ("graphics:350;200;nobuttonbar;position:top;right") winID2 := Window.Open ("graphics:350;200;nobuttonbar;position:top;left") Window.Select (winID1) Window.SetActive (winID1) for i : 1 .. 200     Window.GetPosition (winID1, x1, y1)     Window.GetPosition (winID2, x2, y2)     Window.Set (winID1, "position:" + intstr (x1) + "," + intstr (y1 - 1))     Window.Set (winID2, "position:" + intstr (x2 + 1) + "," + intstr (y2))     delay (10) end for

Ok, what is going on here? Well, it should be evident from the moment you run it. But a point that might escape your notice is the inclusion of the Select and SetActive commands. Notice that the windows still flicker between activation and inactivation. The point being that even if you specify that a window should be active, the moment you call Set upon it or another window, that window becomes active.

We're almost done. One last command in the module. Update. There's not much to say about this one, since it does exactly the same thing as View.Update() except in this one you get to choose which window you're dealing with. This can be useful, if you're using multiple windows. And why wouldn't you be if you were reading this Tutorial? (To enjoy some pinning wit perhaps?)

Have fun with Window.(). It's not too difficult and you can achieve some interesting results. A few points to note:
- output needn't be sent to the currently active window. That is, a window may be hidden and still have output sent to it. This is not the case with input however.
For an example of hidden windows being used for output purposes, check out This programme I made a while back [/shameless plug].
- even if you're not going to use Window.() in its entirety, or even at all, it is a good idea to get into the habit of opening a new window at the onset of any programme you make. This will replace the 'default run window' of Turing and in some cases save you some needless headaches.
- I'll stress again the importance of knowing the difference between an Active and a Selected window. To frolic with Window.() required you to know this.

Ç'est le fin!

Disclaimer: the division between 'basic' and 'advanced' was something of my own creation. It's main purpose was to streamline the layout of this tutorial, and to save me from having to painstakingly spell out some of the finer points later on that should have been self-evident. Any loss of feeling to the knees or neck should not be attributed to the use of this Tutorial.

[[Gandalf]]

Wow, good tutorial, I'll have to get back at it later, I'm a bit tired of reading - but I've been waiting for someone to post up a tutorial for Windows (not the bad kind, the good kind ). Now I can finally do something good with my progs, like dialogue boxes and the sort!

Great job! I'd give you some bits, if my meek amount would mean anything to you .

[Cervantes]

Excellent work, Delos, as always.
+100 bits
/me strolls over to the Turing Walkthrough to make an important incision

[jamonathin]

Very nice. Has everything you need to know about Window.Whatever. GJ. + 25 bits

[bshennette]

Hi, I was just wondering - because I want to open a window the exact size of the regular run window -
What are the dimensions I would use for the ("graphics: __ ; __) part?
Well, I found 650;440 works, but the other thing I wanted to know : How do you get the button bar on the new window? You only show nobuttonbar.

[Coldkick]

The exact amounts for the default window is 640 x 400.

To have the buttonbar appear, instead of typing nobuttonbar type buttonbar

[Srlancelot39]

Excellent tutorial!
Gave me some ideas =P
+25 bits!.....all I can afford =\ lol

[bshennette]

Ya, thanks Coldkick.
Its just, sometimes my computer decides it doesn't believe what I type... lol.