tutorial.basic.9

Tutorial 9: Grids

Introduction

In the last few tutorials we’ve looked at how to customize objects themselves, now we’re going back to positioning and structuring. Putting objects in other objects is a way of making structures, but there are more ways to reach structure in your ui. These ways are called frame stuctures and they refer to when frames are being actively put in certain positions to create a neat ui. We can create grids for example. Making a grid is like making a table, one like this:

IMAGE 41a

Here, every single cell in this table would represent a canvas in uiz. (for canvases, refer to tutorial 5) We’re going to learn how to create such a grid(table) structure in uiz, then how to put things in the cells of it.

Creating a grid

Creating a grid can be easily done using only 3 lines of code.

Line 1: uiz_grid_create(gridw, gridh) : In this function we create our grid and specify the number of cells it should have. Saying the grid would be 5x5 would mean that you would create 25 cells. This function also returns the instance id for your grid, which you will need.

Line 2: uiz_setGridFrames_: This is an important script which is used to tell the grid what type of objects to put in what cell. Not using this script will crash your game. However only call it once, else your game will also crash. It is an extra grid initialization script. Needs to be directly after using uiz_grid_create(). For this group of functions, you have the following options:

uiz_setGridObjects_object(grid, object)
uiz_setGridObjects_script(grid, script)
uiz_setGridObjects_canvas(grid)
uiz_setGridObjects_frame(grid)

This is also a good point to look at the manual. Go to the grids page and look for the four functions above. The _object, _canvas and _frame versions should be fairly easy to use: they just fill every single cell in the grid with one type of object. If you want different cells to have different objects, you will have to use the _script function, or use the parenting system to put your custom objects inside all of the canvases or frames.

Line 3: uiz_fix(instance id): Our good old fixing script. You’ll need this else other weird things will happen.

Creating a grid can be done using this:

EXAMPLE 31:

//initialize uiz
uiz_init()
//create our grid
grid=uiz_grid_create(5,5)
uiz_setGridObjects_object(grid, obj_uiZ_gradientsquare);
uiz_fix(grid)

This will give the following result:

IMAGE 41

In the example we used the _object function to fill our grid with obj_uiZ_gradientsquare objects. This is done because you have already seen this object before and it makes it very clear where our grid cells are.

Sizing the grid

Now, we can see what our grid really looks like. We’ll now focus on resizing the grid. Currently, every single cell in the grid has the same size. Lets change that. You should know that we can’t specify the size of every frame. When we want to specify sizes, we’d have to change the size of that entire row or column. You’ll see that in a minute.

Changing up row/col sizes

The function uiz_gridsize_row and uiz_gridsize_col should be used for this. Look them up in the manual. Go the grid page under "structured" in the wiki sidebar. To use this we need to specify a row/col inside our grid. See the example below:

EXAMPLE 32:

//initialize uiz
uiz_init();
//create our grid
grid=uiz_grid_create(5,5);
uiz_setGridObjects_object(grid, obj_uiZ_gradientsquare);
uiz_gridSize_col(grid,2,100,px);
uiz_fix(grid);

Showing:

IMAGE 43

Now the middle row is resized! A few things to note however:

uiz_gridsize_col comes after uiz_setgridframes().
If you look at the example you might notice we filled in 2, at the place in which we needed to specify the column which we use. Though in the picture we can see that the third frame has changed size. This is because the row/col arguments counts from 0 to the size you specified in uiz_grid_create minus 1. So in our case, 0 would refer to the most left column, while 4 would refer to the right most column. Giving it a col value of 5 will crash your game.
Inside our grid we can use px values, dp values, fc values and xtra values. There are no other value types compatible with grids or other frame stuctures.

The xtra data type

In this section we'll talk about the xtra datatype. This is a datatype which is exclusive to structures like the grid or the frameset (framesets are for a later tutorial). Extra is used to fill in any space not filled up by other cells. If you are familiar with html framesets, this is what the "*" would do.

Let say we have a grid of 3 rows where the first row is 50 pixels, the second row 0.33 fc, and the third is 1 xtra. What will happen is that the first and second row are set to their right size. Now lets say the grid’s parent is 300 pixels tall. The first row will be 50 pixels, the second row will be 100 pixels (300 * 0.33=100) which leaves 150 pixels over. This is where the 1 xtra part comes in handy. The 1 xtra value will take in all space that is left and use that for itself. That is what the xtra data type does: It uses any space that is left. The above example would look like:

EXAMPLE 33:

//initialize uiz
uiz_init();
//create our grid
grid=uiz_grid_create(5,3);
uiz_setGridObjects_object(grid, obj_uiZ_gradientsquare);
uiz_gridSize_row(grid,0,50,px)
uiz_gridSize_row(grid,1,0.33,fc)
uiz_gridSize_row(grid,2,1,xtra)
uiz_fix(grid);

IMAGE 44

What is neat about the xtra data type is that you can have two different rows being that value:

EXAMPLE 34:

//initialize uiz
uiz_init();
//create our grid
grid=uiz_grid_create(5,4);
uiz_setGridObjects_object(grid, obj_uiZ_gradientsquare);
uiz_gridSize_row(grid,0,50,px)
uiz_gridSize_row(grid,1,0.33,fc)
uiz_gridSize_row(grid,2,1,xtra)
uiz_gridSize_row(grid,3,1,xtra)
uiz_fix(grid);

This will give this result:

IMAGE 45

Both the upper frame and lower frame here are 1 xtra. If you compare image 45 to image 44 you can see that both these 1 xtra’s are half the size of the third row. Also the first and last row’s of image 45 combined are the same height as the 1 xtra row on image 44.

Another thing you can do with xtra is that you can still specify the size of something. Right now, we’ve only worked with values of 1 xtra, not 2 extra or 3 xtra. But you can do that. What will happen is that more space is allocated to the row that has 2 xtra, as opposed to the row which has 1 xtra, which is getting smaller.

If you would have two 1 xtra’s, and make them both 2 xtra nothing will change. If you would make the top one 200 xtra and the bottom one 100 xtra, it would give the same effect as if the top one was 2 xtra and the bottom one 1 xtra.

Technical detail: The size in px of an xtra value is calculated by: Space_left(current_xtra_value/all_xtra_values_added_together).*

Here is an example of varying xtras:

EXAMPLE 35:

//initialize uiz
uiz_init();
//create our grid
grid=uiz_grid_create(5,4);
uiz_setGridObjects_object(grid, obj_uiZ_gradientsquare);
uiz_gridSize_row(grid,0,50,px)
uiz_gridSize_row(grid,1,0.33,fc)
uiz_gridSize_row(grid,2,1,xtra)
uiz_gridSize_row(grid,3,2,xtra)
uiz_fix(grid);

IMAGE 46

Compare that with image 45.

It’s always useful for one value in your grid to be an xtra value, to make scaling better.

Putting objects inside your grid

For now, we've only dealt with gradient square. Those don't make for a very nice GUI, now do they? To put different objects inside your grid there are two solutions:

Using a script to fill up all positions
Filling the grid up with canvases and then filling the canvases.

We will go over both methods. The difference is that the script method is better for performance. The canvas objects in your grid don't really do anything, but do take up computing power when uiZ has to handle them. With the script method you circumvent this by putting custom objects inside every grid cell. The script method can be more of a hassle to set up though in GMS1. Also using the canvas method can give more flexibility when you want to swap or change objects later on.

Script method

Let's continue on example 35. Let's say we want the item at column 2, row 1 to be a obj_uiZ_rotator instead of a gradient square. The function which currently fills our grid is uiz_setGridObjects_object. Let's replace this with uiz_setGridObjects_script. As the second argument, we cannot supply obj_uiZ_gradientsquare anymore, we need to give it a script. Make a new blank script. I'm calling this "scr_basictutorial_example_36a_gridObjectCreator", but you may call this whatever.

As the manual says on the grid page under the "uiz_setGridObjects_script" entry in the "Functions" section, our script takes two arguments:

argument0: The column to fill
argument1: The row to fill

What uiZ will do when calling uiz_setGridObjects_script is going over every cell in the grid. For every cell it then calls your script. This means that if you grid is 5x4, your script will be called 20 times! What grid cell is being processed is stated in argument0 and argument1. So if we want a obj_uiZ_rotator at position (2, 1) then we just need to use the arguments in our scripts to check if we need a rotator or obj_uiZ_gradientsquare.

Before we go to our example, I need to tell you how you can tell uiZ in your script what object to use in the cell. Simple: you return an instance! What I mean by this is that your script should ALWAYS return an object created using uiz_c. uiz_c is the create script to create new uiZ objects. So for example, this is a valid script:

///scr_basictutorial_example_36a_test(col, row)
return uiz_c(obj_uiZ_gradientsquare);

This example would do exactly the same as example 35. Now, let's use an if statement to check if we want a rotator or gradientsquare.

///scr_basictutorial_example_36a_gridObjectCreator(col, row)
if argument0 == 2 and argument1 == 1 then{
  return uiz_c(obj_uiZ_rotator);
}else{
  return uiz_c(obj_uiZ_gradientsquare);
}

In our create script we use this:

EXAMPLE 36:

//initialize uiz
uiz_init();
//create our grid
grid=uiz_grid_create(5,4);
uiz_setGridObjects_script(grid, scr_basictutorial_example_36a_gridObjectCreator);//note that we DONT put () after scr_basictutorial_example_36a_gridObjectCreator.
uiz_gridSize_row(grid,0,50,px)
uiz_gridSize_row(grid,1,0.33,fc)
uiz_gridSize_row(grid,2,1,xtra)
uiz_gridSize_row(grid,3,2,xtra)
uiz_fix(grid);

This gives this result:

IMAGE 47

Note that when passing a script to scr_basictutorial_example_36a_gridObjectCreator, we don't use "()". This way we pass a reference to our script, and not to what the script returns.

TODO: GMS2.3 version of the example.

Canvas method

When using uiz_setGridObjects_canvas, our grid is filled with (invisible) canvases. This means that there must be a game maker instance id for each canvas. We need an instance id if we want to do anything with the canvases. You can get the instance id by using the function: uiz_gridObject(grid, col, row). This function requires the grid’s instance id, and the column and row of what you want to get. Just know that the column and rows count from 0 so 0,0 is the top left frame. Here is an example:

EXAMPLE 36:

//initialize uiz
uiz_init();
//create our grid
grid=uiz_grid_create(5,4);
uiz_setGridObjects_canvas(grid);
uiz_gridSize_row(grid,0,50,px)
uiz_gridSize_row(grid,1,0.33,fc)
uiz_gridSize_row(grid,2,1,xtra)
uiz_gridSize_row(grid,3,2,xtra)
uiz_fix(grid);

//get a canvas from the grid
canvas = uiz_gridObject(grid, 2, 2)//do not change anything about this canvas
//add object to grid
rot = uiz_c(obj_uiZ_rotator)
//put the rot inside a canvas that we got from inside a grid
uiz_setParent(rot,canvas)
//make the objet fill the canvas, and therefore fill the cell in the grid
uiz_position(rot, 0,uiz_fill, 0,uiz_fill);
//fix the object
uiz_fix(rot);