grids

Grids

Grids are flexible structures in uiz that allow you to have a structured ui. Grids are like tables in html, word or a lot of different programs that use tables. They are structures with a certain amount of rows(horizontal) and columns(vertical). Grids are less flexible than framesets since they only allow a size to be set for an entire row/col, not for a singe cell. The cells created by grids are just obj_uiZ_canvas, or a custom provided object.

Setup

Setup is fairly easy and you need to do the following:

• create grid base/controller object using uiz_grid_create.
• create all the objects/frames that make up the grid using any of the uiz_setGridObjects_ functions.
• decide how big all the objects/frames that make up the grid should be using uiz_gridSize_.
• fix the grid.

Size types

When you have created your grid, you can size the grid however you want. Use the uiz_gridSize_row and uiz_gridSize_col functions for this. However, these functions take a certain type of size. These are available:

• px: The pixel data type
• dp: The density pixel data type. 1 dp should resemble 1 real life inch as closely as possible.
• fc: The factor data type. 0.5 fc means half the size of the grid, 0.2 fc means a fifth of the grid, etc...
• xtra: Read more below.

xtra

Any row/column sized to xtra will be processed after the size of all other row/column has been calculated, and will be assigned any left space. Multiple rows/columns can have this constant assigned, in which case any space will be divided weighted to the value given by xtra. So if you have two rows/columns, one sized 1 xtra and the other 2 xtra, then the second row/column will have twice as much space as the first row/column. The size of an xtra row/column is calculated using:

(how_many_xtra_for_the_given_row_or_col)/(total_amount_of xtras)*(the_amount_of_space_left)"

It is recommended to make at least one row/column in every division of the xtra type, to make sure your grid fills itself in a pixel-perfect manner. For example, making 3 rows/columns of 0.33fc each can create a unfilled pixel line. In this example, using 3 rows/columns of 1xtra would be better. Xtra rows/columns may not always be the same size. In the given example, one of the rows/columns would get an extra pixel to prevent free space.

Functions

To create or manipulate the grid, use these functions:

• grid = uiz_grid_create(gridw, gridh): Creates a grid. The grid will always use uiz_fill for it's size and position, so don't change that. After calling this function, the grid doesn't work yet and will create errors. You still have to call one of the uiz_setgrid_ functions to create the actual objects inside of the grid.

  • grid: Returns the instanceid of the grid object that was created.
  • gridw: how many columns the grid should have.
  • gridh: how many rows the grid should have.

• uiz_setGridObjects_object(grid, object): Fills a grid up with a given object at argument1 so every time you call uiz_gridObject() it will return the instance id of the specified object. ONLY CALL THIS SCRIPT ONCE AFTER CREATING THE GRID.

  • grid: The instance id of an obj_uiZ_grid object which you want to modify or read data from.
  • object: What object every cell in the grid should be filled with.

• uiz_setGridObjects_script(grid, script): Fills a grid up with certain objects. It will do this by checking the return value of a script specified at argument1. This script is useful if you for example want to have one row filled up with a certain type of object and another row with another. ONLY CALL THIS SCRIPT ONCE AFTER CREATING THE GRID.

  • grid: The instance id of an obj_uiZ_grid object which you want to modify or read data from.
  • script: The script to call for every frame. Your script gets 2 arguments: and x and a y value which start at zero and go up to your grid width or height (but won't ever be equal to them). From these 2 values you will need to make your script return a valid instance id, not an object_index. This instance id must be different for every value inputted to the script or else conflicts can occur. You can use uiz_c() to create instances.

• uiz_setGridObjects_canvas(grid): Fills a grid up with obj_uiZ_canvas so every time you call uiz_gridObject() it will return the instance id of an obj_uiZ_canvas. ONLY CALL THIS SCRIPT ONCE AFTER CREATING THE GRID. Although not as bad as grids, it might be slightly more performance intensive if you use canvases (uiz_setGridObjects_canvas()) for everything if you just like to have a row of buttons or something. In that case uiz_setGridObjects_object uiz_setGridObjects_script might be a better solution.

  • grid: The instance id of an obj_uiZ_grid object which you want to modify or read data from.

• uiz_setGridObjects_frame(grid): Fills a grid up with obj_uiZ_frame so every time you call uiz_gridObject() it will return the instance id of an obj_uiZ_frame. ONLY CALL THIS SCRIPT ONCE AFTER CREATING THE GRID. It might be slightly more performance intensive if you use frames (uiz_setGridObjects_frame()) for everything if you just like to have a row of buttons or something. In that case uiz_setGridObjects_object uiz_setGridObjects_script might be a better solution.

  • grid: The instance id of an obj_uiZ_grid object which you want to modify or read data from.

• cell_instanceid = uiz_gridObject(grid, x, y): Returns the instance id of the cell at the specified row and col inside the grid.

  • cell_instanceid: The instanceid of the cell at the given x and y.
  • grid: The instance id of an obj_uiZ_grid object which you want to modify or read data from.
  • x: The column in the grid from which to get the cell.
  • y: The row in the grid from which to get the cell.

• uiz_gridObject_set(grid, x, y, instanceid): Sets the instance id of the cell at the specified row and col inside the grid. Note that the old object may still exist, and you may lose any handle to it. It is recommended to read the current object using uiz_gridObject, then to call this function after which you can destroy or move the old instance.

  • grid: The instance id of an obj_uiZ_grid object which you want to modify or read data from.
  • x: The column in the grid from which to get the cell.
  • y: The row in the grid from which to get the cell.
  • instanceid: What uiZ object should be placed at the position of the cell.

• uiz_gridSize_col(grid, column, size, sizeType): Allows you to set the size of a specific column within a grid structure. For this, you need to know the id of the already existing grid, which column you want to edit and the new size. If you resize a certain column then all frames in that column will get that width.

  • grid: The instance id of an obj_uiZ_grid object which you want to modify or read data from.
  • column: The column number in the grid you want to resize. This starts from 0 and goes up to (but not includes) your grid width.
  • size: The new size of your column, in the given sizeType.
  • sizeType: The type of size you want your column to be. You can choose from:
    • px
    • dp
    • fc
    • xtra

• uiz_gridSize_row(grid, row, size, sizeType): Allows you to set the size of a specific row within a grid structure. For this, you need to know the id of the already existing grid, which row you want to edit and the new size. If you resize a certain row then all frames in that row will get that width.

  • grid: The instance id of an obj_uiZ_grid object which you want to modify or read data from.
  • row: The row number in the grid you want to resize. This starts from 0 and goes up to (but not includes) your grid width.
  • size: The new size of your row, in the given sizeType.
  • sizeType: The type of size you want your row to be. You can choose from:
    • px
    • dp
    • fc
    • xtra

• columns = uiz_grid_cells_w(grid): Returns the amount of columns in the grid.

  • columns: The amount of columns in the grid.
  • grid: The instance id of an obj_uiZ_grid object which you want to modify or read data from.

• rows = uiz_grid_cells_h(grid): Returns the amount of rows in the grid.

  • rows: The amount of rows in the grid.
  • grid: The instance id of an obj_uiZ_grid object which you want to modify or read data from.

• uiz_grid_addCol(grid): Adds one extra column to a grid. Only takes one argument (the grid object id) and sets the size of the extra row/col to "1 xtra".

  • grid: The instance id of an obj_uiZ_grid object which you want to modify or read data from.

• uiz_grid_addRow(grid): Adds one extra row to a grid. Only takes one argument (the grid object id) and sets the size of the extra row/col to "1 xtra".

  • grid: The instance id of an obj_uiZ_grid object which you want to modify or read data from.

• uiz_combineGridCells(grid, col1, row1, col2, row2): A VERY HOT SCRIPT. Call only after you're sure that the grid doesn't need to be adjusted (normal position fixing scripts are ok). Gets 2 cells in a grid and makes them and everything between them into one cell. The "row1" and "col1" arguments need to be the most top-left cell and the "row2" and "col2" you most bottom-right cell. Because this overlaps some references, there might be some problems when trying to resize the grid afterwards (or even problems in general). To get a reference to this new cell, use uiz_gridObject on any of your positions.

  • grid: The instance id of an obj_uiZ_grid object which you want to modify or read data from.
  • col1: The column number of your top-left most cell starting from 0.
  • row1: The row number of your top-left most cell starting from 0.
  • col2: The column number of your bottom-right most cell starting from 0.
  • row2: The row number of your bottom-right most cell starting from 0.

Property Variables

The obj_uiZ_grid object contains the following properties:

• marginl[0]: A pixel value of margins to add to the left side of the grid (not the individual cells themselves.)
• marginr[0]: A pixel value of margins to add to the right side of the grid (not the individual cells themselves.)
• margint[0]: A pixel value of margins to add to the top side of the grid (not the individual cells themselves.)
• marginb[0]: A pixel value of margins to add to the bottom side of the grid (not the individual cells themselves.)
• margincellw[0]: A pixel value of margins give the cell size both on the left and right. (so a value of 3 will add a margin to the left and right size.)
• margincellh[0]: A pixel value of margins give the cell size both on the top and bottom. (so a value of 3 will add a margin to the top and bottom size.)
• marginsonsideslr[false]: Whether there should be margins on the left side of the very left cell and margins on the right side of the very right cell of the grid.
• marginsonsidestb[false]: Whether there should be margins on the top side of the very top cell and margins on the bottom side of the very bottom cell of the grid.
• gridw: The amount of columns in the grid.
• gridh: The amount of columns in the grid.
• rowsize: Holds a list of all rows with their sizes.
• rowsizetype: Holds a list of all rows with their size types.
• colsize: Holds a list of all rows with their sizes.
• colsizetype: Holds a list of all rows with their size types.