# Backgrounds

In UI, you might want to apply a certain style to your widgets/objects. Your checkbox might have the same border as your string input box. To make this happen uiZ utilizes a concept called "backgrounds". A background is just a standard template on which the rest of the object can be drawn.

In short "Object background & stitching" is just a collection of scripts and other code running on multiple objects within uiz to give these items a "background".
This could be just a simple square, or a sprite or something.
There are also methods which combine different parts of sprites together to create the desired effect.  
Here are some different types of object backgrounds, applied to a stringbox.  
<img src="objects/backgrounds1.png">

## Backgrounds in a nutshell

Basically a background can have these properties:

* sprite
* color
* margin
* texturemode

How these variables are interpreted exactly depends on the background type used. These types are available:

* uiz_back_square
* uiz_back_square_outlined
* uiz_back_spritestitch_horizontal
* uiz_back_spritestitch_vertical
* uiz_back_spritestitch_specialmargins
* uiz_back_spritestitch
* uiz_back_sprite
* uiz_back_circlestitch
* uiz_back_circlestitch_specialmargins
* uiz_back_circlestitch_horizontal
* uiz_back_spritestitch_4way
* uiz_back_spritestitch_4way_plus

Furthermore a background can be in any four states depending on how the mouse interacts with it:

* **normal:** the mouse is not over the object
* **over:** the mouse is hovering over the object but not clicking it
* **in:** the mouse is hovering over the object and clicking the left button
* **out:** object specific interpretation, see if your object supports this state. By default this state is not used.

Depending on the state of the object different background parameters and types can be selected.

## Stitching

"Stitching" refers to the "stitching of sprites". 
For example, a button might have seem like one single image, but it is in fact build up out of several sprites.  
<img src="objects/backgrounds2.png">  
When these different sprites are being combined into one sprite, that is called "stitching" in uiz.

## Variables

There are quite a few variables to control objects backgrounds and sprite stitching, but a lot of them are quite the same. This is basically the "Backgrounds in a nutshell chapter explained".

### Basic variables

* **texturescript[uiz_back_circlestitch]:** This is the variable that holds what technique/type of background should be used on this object. This should be a reference to a game maker script.
You can use one of the build in uiz_back_ methods as shown above, or you can even create your own script.
Just make a new script and you can now use all the uiZ object variables and your background is automatically contained (see ["**Containment in general**"](containment)).

There is also a texturescript_over, _in and _out for the different mouse states. These are -1 by default meaning that the value of "texturescript' will be used. If you change the value of these scripts, a different background script will be used whenever the mouse interacts with your object in a different way.

* **sprite_texturemode[uiz_texturemode_fill]:** This can be either **uiz_texturemode_fill, _tile or _tilefit**.
This always says something about the middle part of the sprite. If border_texturemode is set to -1, the sprite_texturemode also says something about the border.  
These are your options:

  * **Fill** will strech out the sprite.
  * **Tile** will repeat the sprite where every pixel on the sprite will be a pixel on your screen.
  * **Tilefit** will repeat the sprite, but it will make sure that no halves of sprites are used as can occur with the normal tile.

  (Look at [**"texturemodes"**](texturemodes) for more info and pictures for each mode.)

* **border_texturemode[-1]:** This can be either uiz_texturemode_fill, _tile or _tilefit. Can also be -1 meaning that the texturemode of sprite_texturemode will be used.

### Basic functions

The above mentioned variables can also be set using these functions:

* **uiz_background_texturescript(instanceid, script):** Sets the texturescript to use for the background.
  * **instanceid:** the instance id of the instance you want to modify
  * **script[uiz_back_circlestitch]:** What GML script should be executed to draw an object background. For a list of possible values scroll down to "Available backgrounds and stitching modes", or make a script yourself.

* **uiz_background_texturescript_ext(instanceid, normal, over, in, out)** Sets the texturescript to use for each state an object can be in. For a list of possible values scroll down to "Available backgrounds and stitching modes", or make a script yourself.
  * **instanceid:** the instance id of the instance you want to modify
  * **normal[uiz_back_circlestitch]:** What GML script should be executed to draw an object background when the mouse is not over the object. Don't set this to -1, or any other invalid value.
  * **over[-1]:** What GML script should be executed to draw an object background when the mouse is over the object. Set this to -1 to inherit the value from "normal".
  * **in[-1]:** What GML script should be executed to draw an object background when the mouse is clicking the object. Set this to -1 to inherit the value from "normal".
  * **out[-1]:** What GML script should be executed to draw an object background when an object is specified to do so (when this shows up is object-specific and not implemented for most objects.). Set this to -1 to inherit the value from "normal".

* **uiz_background_texturemode(instanceid, sprite[uiz_texturemode_fill], [border[-1]]):** Specifies how sprites should be drawn by the texturescript.
  * **instanceid:** the instance id of the instance you want to modify
  * **sprite[uiz_texturemode_fill]:** What this exactly means differs per texturescript. In most cases it determines the texturemode for sprites drawn across or in the middle of your background If border_texturemode is set to -1, the sprite_texturemode also says something about the border. 
  Look at [**"texturemodes"**](texturemodes) for more info and pictures for each mode. These values can be given as argument:

    * **Fill** will strech out the sprite.
    * **Tile** will repeat the sprite where every pixel on the sprite will be a pixel on your screen.
    * **Tilefit** will repeat the sprite, but it will make sure that no halves of sprites are used as can occur with the normal tile.
  * **border_texturemode[-1]:** This texturemode refers to the texturemode to use around the edge of your background. The exact implementation may differ per texturescript. This can be either uiz_texturemode_fill, _tile or _tilefit. For more info see the sprite argument or [**"texturemodes"**](texturemodes). Can also be -1 meaning that the texturemode of sprite_texturemode will be used.




* **uiz_background_set(instanceid):** Recalculates all background values specified in previous functions (or variables). When changing properties of the background, these properties aren't always directly applied to the background so this function is required if you are not already "fixing" the object by calling uiz_fixgeneralpos(instanceid).
  * **instanceid:** the instance id of the instance you want to modify
* **uiz_background_setEnabled(instanceid, enabled):** Enables or disables the use of background on a certain object. For this to work the object does need to be compatible with background. Most objects come with backgrounds enabled by default. You can easily check if your object is compatible with backgrounds by checking the manual (see objects in sidebar). You might also need to 'set' the background using uiz_background_set in case you aren't already planning on 'fixing' the object (using something like uiz_fixgeneralpos).
  * **instanceid:** the instance id of the instance you want to modify
  * **enable:** Whether to enable or disable the use of backgrounds on this object.

The functions listed above also exist in the \_topbar\_ and \_item\_ flavours. These are required for certain objects like the [**window**](windows) or [**mouse menu**](mousemenu).

### Normal variables

These variables are used when the mouse isn't interacting with the object in any way.  
*These values are also used when non normal values haven't been specified (e.g. are "-1". As an example: if color_in is set to -1 and color_normal is set to c_red, your object will have a red background when the mouse clicks your object, and when it isn't hovering over your object).*

* **sprite_normal[spr_uiZ_border1]:** What sprite to use.
* **color_normal[c_white]:** What color the background should be.
Can either be used as a plain color, or used to blend an image.
* **margin_normal[5]:** This variable is required by some texturescripts. Its use can differ from texture script, but mostly refers to the size of your sprite or border. Most objects obey this variable by making sure not to draw anything else outside the margin.

The function listed above also exist in the \_topbar\_ and \_item\_ flavour. These are required for certain objects like the [**window**](windows) or [**mouse menu**](mousemenu).

### Normal functions

The above mentioned variables can also be set using these functions:

* **uiz_background_normal(instanceid, sprite, color, margin):** Set the settings of the background when the mouse is **not** hovering over the object. (May be slightly different for different objects). The interpretation of each of the following values differ per script.
  * **instanceid:** the instance id of the instance you want to modify
  * **sprite:** What sprite the texturescript should use.
  * **color:** What (blending) color the texturescript should use.
  * **margin:** What margins the texturescript should handle.

The function listed above also exist in the \_topbar\_ and \_item\_ flavour. These are required for certain objects like the [**window**](windows) or [**mouse menu**](mousemenu).

### Over variables

A set of variables doing the same thing as their normal counterparts, but these values are used instead of the normal ones when the mouse hovers over the object.
Also, when making any of these values -1, the normal versions are using instead. (This is evaluated individually for every variable)

* **sprite_over[spr_uiZ_border1_over]**
* **color_over[-1]**
* **margin_over[-1]**

### Over functions

The above mentioned variables can also be set using these functions:

* **uiz_background_over(instanceid, sprite, color, margin):** Set the settings of the background when the mouse is hovering over the object. (May be slightly different for different objects). The interpretation of each of the following values differ per script.
  * **instanceid:** the instance id of the instance you want to modify
  * **sprite:** What sprite the texturescript should use.
  * **color:** What (blending) color the texturescript should use.
  * **margin:** What margins the texturescript should handle.

The function listed above also exist in the \_topbar\_ and \_item\_ flavour. These are required for certain objects like the [**window**](windows) or [**mouse menu**](mousemenu).

### In variables

A set of variables doing the same thing as their normal counterparts, but these values are used instead of the normal ones when the mouse clicks the object.
Also, when making any of these values -1, the normal versions are using instead. (This is evaluated individually for every variable)

* **sprite_in[spr_uiZ_border1_in]**
* **color_in[-1]**
* **margin_in[-1]**

### In functions

The above mentioned variables can also be set using these functions:

* **uiz_background_in(instanceid, sprite, color, margin):** Set the settings of the background when the mouse is clicking the object. (May be slightly different for different objects). The interpretation of each of the following values differ per script.
  * **instanceid:** the instance id of the instance you want to modify
  * **sprite:** What sprite the texturescript should use.
  * **color:** What (blending) color the texturescript should use.
  * **margin:** What margins the texturescript should handle.

The function listed above also exist in the \_topbar\_ and \_item\_ flavour. These are required for certain objects like the [**window**](windows) or [**mouse menu**](mousemenu).

### Out variables

A set of variables doing the same thing as their normal counterparts, but these values are used some rare occasions when an object might be "activated" and a different sprite should be used when hovering over that object. This requires the object to have some custom code specifying when "out" can be used.
Also, when making any of these values -1, the normal versions are using instead.(This is evaluated individually for every variable)

* **sprite_out[spr_uiZ_border1_in]**
* **color_out[-1]**
* **margin_out[-1]**

### Out functions

The above mentioned variables can also be set using these functions:

* **uiz_background_out(instanceid, sprite, color, margin):** Set the settings of the background when it is in the "out" state. (Implementation is different for different objects and most objects never use this state). The interpretation of each of the following values differ per script.
  * **instanceid:** the instance id of the instance you want to modify
  * **sprite:** What sprite the texturescript should use.
  * **color:** What (blending) color the texturescript should use.
  * **margin:** What margins the texturescript should handle.

The function listed above also exist in the \_topbar\_ and \_item\_ flavour. These are required for certain objects like the [**window**](windows) or [**mouse menu**](mousemenu).

## Available backgrounds and stitching modes

Uiz comes with a few background types:

### uiz_back_square

Only uses the color values and just draws a unrounded square using those colors. Margins make the square smaller.

### uiz_back_square_outlined

Alike uiz_back_square, but this one has a single pixel black outline.

### uiz_back_spritestitch_horizontal

Uses the sprite and color values. This will stitch together a sprite which exists out of 3 parts: A left, middle and right part. The sprite can be defined in 3 ways:

* As just one normal sprite existing out of 3 sub images which never changes color when the mouse goes over it.
* As 3(or 4) separate sprites (a normal, over, in or rarely an out.) existing out of 3 sub images. This way the sprite changes when the mouse interacts with an object.
* As 1 sprite containing either 9 or 12 sub images. This way of defining your sprite will require you to set sprite_over, sprite_in (and sprite_over) to "-1" . Once setup, sub images 0-2 will normally be used.
When the mouse hovers over the object sub images 3-5 will be used.
And when the mouse clicks the object, or the object is activated sub images 6-8 will be used.
Optionally 9-12 can be used for some objects who need it.
The sprites on the left and right will be drawn, but might be scaled to fit the object.
The middle part will scale accordingly to sprite_texturemode which can be either "**uiz_texturemode_fill**", "**uiz_texturemode_fill_edgeless**", "**uiz_texturemode_tile**" or "**uiz_texturemode_tilefit**".  
When there isn't enough space to draw the sprites, the 2 most outer sides will be drawn partially.

### uiz_back_spritestitch_vertical

The same as uiz_back_spritestitch_horizontal, but then rotated 90 degrees.  
It is worth to note that requires a sprite that is horizontal. Meaning that you can give this mode the exact same sprite as on the horizontal spritestitch variant.  

### uiz_back_spritestitch

This mode looks whether uiz_back_spritestitch_horizontal or uiz_back_spritestitch_vertical is better to use, and calls that function.

### uiz_back_sprite

Just draws a sprite, but sprite_texturemode still has effect on this background.

### uiz_back_circlestitch

This draws a background which is made up of 9 different sprites: 4 corners, 4 edges and a center. The advantage of this approach is that your can make your object any size, while still having it look good. To learn how to use this mode you will have to check out it's seperate page [**here**](backgrounds/circlestitch).

### uiz_back_circlestitch_specialmargins

Like uiz_back_circlestitch, but will allow you to have the corner piece be a custom size. To learn how to use this mode you will have to check out it's seperate page [**here**](backgrounds/circlestitch_specialmargins).

### uiz_back_circlestitch_horizontal

This does almost the same as the normal uiz_back_circlestitch, but then it doensn't draw any corners or top or bottom pieces.  
Margins around those areas are also ignored.

### uiz_back_spritestitch_4way

Utilizes the sprite_ and color_ variables.  
This takes a sprite containing 1 subimage and draws it into one square by rotating and drawing the sprite 4 times.
A sprite should be build up in this way:

* **image 0:** the bottom-right piece.

### uiz_back_spritestitch_4way_plus

Utilizes the sprite_, sprite_texturemode and color_ variables.
This takes a sprite containing 1 subimage and draws it into one square by rotating and drawing the sprite 4 times.
But when the sprite isn't a perfect square, the proportion of the corner pieces is kept 1:1 and the corners are connected through another sprite (subimage 1) which will draw accordingly to the sprite_texturemode.
sprite_texturemode doesn't affect the corners.
A sprite should be build up in this way:

* **image 0:** the bottom-right piece. (Will be rotated)
* **image 1:** the top straight piece.
* **image 2:** the left straight piece.

The sprite should also be a square. (The width and height should be the same)

## Writing your own texture script

To write your own texturescript, you just make a script and set it to an object using *uiz_background_texturescript(instanceid, script)* for example. Then, you can use these variables:

* **rx:** The upper left x coordinate of the outer boundary of your object.
* **ry:** The upper left y coordinate of the outer boundary of your object.
* **rlx:** The bottom right x coordinate of the outer boundary of your object.
* **rly:** The bottom right y coordinate of the outer boundary of your object.
* **width:** The width of the outer boundary of your object.
* **height:** The height of the outer boundary of your object.
* **bkmar:** The margin given to your background. You may use this however you see fit.
* **bkspr:** The sprite given to your background. You may use this however you see fit.
* **bkcol:** The color given to your background. You may use this however you see fit.
* **sprite_texturemode:** The texturemode you can use for the main part of your background.
* **border_texturemode:** The texture mode you can use for the edge of your background.