UISprite

[ArenMook]

Overview

UISprite is the bread-and-butter of NGUI. It's a drawn sprite pulled from a texture atlas. Like other widgets, it inherits all the functionality of the UIWidget.

• All sprites require an Atlas to be created first. Clicking the Atlas button will bring up a list of all the atlases in your project. To create a new atlas, use the Atlas Maker tool (NGUI -> Open -> Atlas Maker).
• You can click the Edit button next to your Sprite selection to edit the selected sprite. This is also how you can add a border to your sprite, making it suitable to be 9-sliced.
  
• By default, the newly added sprites are going to be of Simple type. This means they will be drawn much like UITextures, except their data will be coming from the atlas.
  
• You can change the Sprite Type to be Filled if you're doing a cooldown timer or a progress bar.
  
• You can change the Sprite Type to be Tiled if you want your sprite to repeat over and over, filling the area. It's best to not use small sprites for this as doing so will create too many triangles. It's also a good idea to give your sprite a 1 pixel border so that seams will be eliminated.
  
• You can change the Sprite Type to be Sliced if you want to enable 9-slicing on your sprite. For this to work correctly you need to specify a Border on your sprite (click the Edit button above). An example of a sliced sprite would be a button's background.
  

Choosing the "Make Pixel-Perfect" option from the context menu will make the UISprite assume its original size. So if the source texture was 300 by 200 pixels, the width and height of your UISprite will be adjusted to exactly those dimensions. Note that this will not be the case with Tiled and Sliced sprites -- they have their own set of rules.

Pro-Tip #1

NGUI will automatically use the last selected atlas and sprite when creating new ones. This means if you have the Atlas Maker open and choose some sprite within, you can quickly create it by hitting ALT+SHIFT+S. Although note that duplicating the selected object is even easier (CTRL+D).

Pro-Tip #2

To change the sprite via code, use its spriteName:

1. UISprite sprite = GetComponent<UISprite>();
2. sprite.spriteName = "Some Sprite";

Just make sure that "Some Sprite" actually exists in the atlas! It's case sensitive.

Class Documentation

http://tasharen.com/ngui/docs/class_u_i_sprite.html

If you have a question regarding this component or would like me to clarify something, just post a reply here.

[zipper]

It would be super nice to have a "use antialiasing" option for the fill.

[ArenMook]

There will be anti-aliasing if your project has it enabled. It's a hardware setting that smoothes edges of geometry. There is no way to smooth it via code without creating a render texture and modifying a render texture instead of simply adjusting vertices like NGUI does right now.

[lzt120]

if use the same sprite but in different alpha for example I have for alpha in 25%,50%,75% and 100%  and will this result in performance issue ?

[ArenMook]

Not sure what you're do that for, lzt120? If it's the same sprite and you just change the alpha infrequently, there is no performance change from something like that. If you change the alpha every frame, then yes, there will be a performance hit. If you overlay the same sprite on top of the other, then you will also get a performance hit but due to something else entirely -- hardware fillrate limitations. It'll only be noticeable on mobile devices, and even then, marginally so.

[charliehelman]

Is there a way to adjust the dimension sizes of sprites uniformly in the scene view? Before sprites had dimensions, I would just use the unity scale tool, but now this feels like the wrong thing to do (is it?).

I intuitively expected this to happen when holding SHIFT while adjusting size with the handlers, just like in photoshop (like with the free transform tool).

Does this feature exist in the current version of nGUI?

Also, is there a way to enable snapping while adjusting widget sizes? Having this feature currently when moving sprites is fantastic, but while arranging ui layouts I found myself constantly adjusting dimensions, moving to snap to center, adjusting dimensions again just to try and get the alignment to look good. Obviously the widget  unified alignment options in the inspector fix this problem but I usually don't set those up until after I have the widget arranged the way I want. Edit: I now better understand the widget anchoring options (I was using them wrong, lol). I think I understand Anchoring is a separate feature than snapping while scaling (though some use cases may overlap).

Sorry if part of this belongs in the feedback section.

[ArenMook]

Snapping only works when moving the widget, it doesn't work for adjusting the widget's dimensions.

You can adjust the widget while keeping its proportions by setting its Aspect Ratio to something other than "Free".

[charliehelman]

You can adjust the widget while keeping its proportions by setting its Aspect Ratio to something other than "Free".

Ah, I see. I messed around for a few minutes with the aspect ratio options earlier but didn't understand why it wasn't working. I must have accidentally set the ratio value, which wasn't clear to me until your response.

Setting the aspect ratio to Free and then back to Width based reverted the ratio value correctly and the sprite then scaled correctly.

Thank you sir.

EDIT: After some more tinkering, I might have discovered a bug which is what caused my confusion.

Swapping out sprites does not update the aspect ratio value. You have to set it to free, to another option, then back to free before the value actually updates. Intuitively I would expect the value to update whenever the sprite is changed.

[ArenMook]

Changing the sprite won't change the dimensions of the widget either. You have to call MakePixelPerfect() for it to change dimensions.

[MoProductions]

Hello.  I've used NGUI for a few things in the past but my new project is 100% 2D GUI so I now have to become the master.  I've been fiddling around and can't seem to find answers to my first couple of questions:

1) I'm creating a sprite out of a 640x1136 (iPhone 5) image, but the sprite ends up being 576x1024, even if I click on the "snap" button.  I ended up adjusting the size myself with the dimensions, but even when I try the "make pixel perfect using the context menu" instructions it goes back to 576x1024.  Is there a way to adjust this, and/or does it have something to do with the power of 2 height?

2) I'm not exactly sure how my boss wants to handle screen resizing, but I was when going from 640x1136 (iPhone 5) to 640x960 (iPhone 4) the image would scale down proportionally so that there was extra space on the sides.  I wanted it to scale to fill the screen, which I had done with UIStretch, but the docs say UIStretch is deprecated and to use Widgets and Panels instead.  I've tried everything with those and can't seem to get the same result.  Can you let me know what I'm missing?

Thank you.  Looking forward to mastering this plugin!
-Mo

[ArenMook]

1. Don't add such large textures to an atlas. Use UITexture to draw them. Also keep in mind that 640x1136 is not a power of two image, so be aware of that. It's rarely a good idea to do this to begin with. It's almost always better to create a composite background, made up from several elements, overlapping to create the desired more complicated looking result. You can save an incredible amount of texture memory this way.

2. Use the anchoring on the widget itself. Anchor only 2 sides (top and bottom), and specify an aspect ratio on the widget (based on height).

[Fractalbase]

I want to create a UISprite, without the center filled, so that the center has specific dimensions.  What are the dimensions that the sprite should be in order for the center to have dimensions of say 192x192?  Also, is there a way to specify the color of the center (separate from the border)?

[ArenMook]

I don't understand your question. UISprite without the center filled? What does that mean?

If you're trying to adjust the position of the sprite's center, and it's a sliced sprite, then it's a simple matter of knowing the desired center size (192x192 in your case) and adding the UISprite.border. Note that the border is a Vector4 in the following order: X = left, Y = bottom, Z = right, W = top.

[Fractalbase]

Sorry for so many questions.  I've added game objects to my scene, and adjusted the hierarchy.  Now my sprites have position x&y values that are way far away (e.g., -20000).  I can't seem to changes these values.  What would cause that?  How can I fix that?

[ArenMook]

Without knowing what your hierarchy is like I can't comment much. Try creating a UI from scratch and see where you went wrong.

Also never re-parent widgets to some random game object. This is just plain bad. Widgets need to be under the UIRoot (or if you're an advanced user -- under a UIPanel somewhere in your world). Even if you do want to simply to group widgets underneath your UI, use ALT+SHIFT+N to create a child game object underneath the selected object, not a random game object in the middle of nowhere like Unity does when you do it via the GameObject menu.