tutorial.basic.11

Tutorial 11: Windows

Introduction

Windows! Finally. A pretty nice and useful feature to use in uiz.

Window usage workflow

Creating windows exists out of multiple parts:

Creating your window and defining it’s size.
Customizing your window (backgrounds, colors)
Fixing your window
Putting stuff in your window

Those are a lot of steps, but we are going to run you through them one a time.

Creating a window

Creating your window is fairly easy, you can use either uiz_window_create, or use uiz_window_create_animation. Look up these functions in the manual. In the sidebar there is a entry called "windows (uiZ)". There is also "windows (os)", but you won't need those as they are functions only applicable to Microsoft Windows. We want to use the uiZ built in windows.

EXAMPLE 40a:

//initializing uiz
uiz_init();
//creating window
window=uiz_window_create_animation(3,dp,3,dp,uiz_anticipate_in,uiz_anticipate_out,uiz_one,1);
//fixing window
uiz_fix(window);

This creates an empty window:

IMAGE 53a

Putting stuff inside a window

To put stuff inside this window, you don't actually need to learn anything new. Putting things inside a window is handled by uiZ's parenting system from tutorial 2.

EXAMPLE 40b:

//initializing uiz
uiz_init()
//creating window
window=uiz_window_create_animation(3,dp,3,dp,uiz_anticipate_in,uiz_anticipate_out,uiz_one,1)
//fixing window
uiz_fix(window)

//add gradient
gradient = uiz_c(obj_uiZ_gradientsquare);
uiz_setParent(gradient, window);//put the gradientsquare inside the window
uiz_position_t(gradient, uiz_fill, uiz_fill);//fill the window with the gradient
uiz_fix(gradient);

This yields:

IMAGE 53b

Customizing window background

To change the look and feel of the window, it uses the background system as explained in tutorial 8. However, something interesting is going on with the window: it has got two backgrounds. You can see this on the window as one big background, and a second one for the top bar. For the main background, you can use the normal uiz_background_ functions, about which you can read more about in tutorial 8, or on the background documentation page.

However, if you want to change the top bar, you need to use the uiz_background_topbar_ functions. For almost every normal uiz_background_, there exists a _topbar_ variant.

Let's see an example where we change the colors of our window:

IMAGE 53c

Well, that's what I call a not so merry christmas! But I'm sure you can come up with styles that do look absolutely fabulous.

Background states

Before moving onto the next topic, it must be explained that a window handles it background differently. These states exist in these conditions:

_normal: The window is not selected.
_in: The window is selected.
_over: The window is not selected and the window is maximized.
_out: The window is selected and the window is maximized.

Further customization

Go on, take a look at the manual on how to change more window settings. You can change:

what buttons should show. (enable/disable minimize, maximize and close)
what buttons should look like. (customize minimize, maximize and close)
what the backgrounds look like, besides just the color
Set the window text and customize it
Set how the top bar is put inside the window
Set how and if the window can be resized.
Programmatically minimize of maximize the window.

Popup

Besides you being able to completely make your own windows, there are some standard “quick windows” to use. For example, you may want to make a quick popup with an “ok” button or something. Well, There are pre made scripts that do just that in uiz!

Here is a list of them:

Uiz_popup_ok
Uiz_popup_yesno
Uiz_popup_string

Ok popup

They are very easy to use, just look at an example:

EXAMPLE 41:

//init uiz
uiz_init()
//create popup window
window=uiz_popup_ok("This is a test popup","A window!",true)//we will need to store window for later usage
//no fixing or anything else is needed

IMAGE 54

To find these functions in the manual, open up the popup section of the wiki sidebar. Click on the uiz_popup_ok entry to see what this function does.

Now the “block background” argument in the function is kind of interesting. It allows you to make everything in the background unclickable and forces the user to put all attention on your popup. Enabling this function will “gray out” everything behind the message. This argument is set to true in the example above. How to get if the ok button has been pressed? Well, you have to check if the window still exists. You can easily do this by checking:

If !instance_exists(window) then{
//execute code
}

I would recommend putting the code into your step event if you are doing some process that has been interrupted to show the user a message. In the upcoming updates, the handling should be changed to something event based. For now, this is not the case.

Boolean popup

Next window, The yes/no window. You can create it in very much the same style:

EXAMPLE 42:

//init uiz
uiz_init()
//create popup window
r=uiz_popup_yesno("Do you like uiz?","Important question!",false)
//no fixing or anything else is needed

IMAGE 55

So how do I get the answer of this box? Well it’s a little big more complicated. First because game maker can only return a single value, the local object variables: “uizreturnyes”, “uizreturnno” and “uizreturnwindow” will be created after you run the script.

Uizreturnyes now has a instance_id referring to the yes button and uizreturnno has a instance id referring to the no button. Also why have a uizreturnwindow variable? Well, the function uiz_popup_yesno doesn’t always return a window instance id. Normally it should return a window instance id, but when a "block background" is set to true, then it will return the instance id of a obj_uiZ_square which overlays the entire screen. (This is also true for the normal uiz_popup_ok, but it doesn’t really matter there)

Another way of getting the buttons is by accessing “yesbutton” and “nobutton” on whatever uiz_popup_yesno returns. This will work whether the script returns a window or a square.

Knowing all of this, the following code can be used to get the answer of a popup_yesno, where r refers to a value previously gotten in example 42 :

if instance_exists(r.yesbutton) and r.yesbutton.kmouseover == uiz_mouseclick then{
    //yes!
}else{
    if instance_exists(r.nobutton) and r.nobutton.kmouseover == uiz_mouseclick then{ //no!
    }
}

In later versions of uiZ, this code will be cleared up to be more event based.

Don’t worry if you don’t understand every little bit of code in there but it is useful to know what kmouseover does, which you will learn in the next tutorial. This code though, does need to be in a step event to constantly check if you want to know the answer. The “//yes!” and “//no!” parts only fire for 1 step long.

String input windows

And last but not least, string input windows. This also works very similar to other popup scripts:

EXAMPLE 43:

//init uiz
uiz_init()
//create popup window
window=uiz_popup_string("what is your name?","Something...", true, "david")
//no fixing or anything else is needed

IMAGE 56

Now we can "get" the string using:

if instance_exists(r) and r.indestroy=1 then{ string=r.str;}

End of tutorial

I hope this tutorial was useful to you. Personally I'm not to happy with it because the way to use the popups is convoluted and bad programming practice. The popup system needs a big overhaul, but for now you unfortunately need to live with the current system.

In this tutorial you learned: