UIGradient
UIGradient is a UIComponent that applies a color and transparency gradient to the UI elements rendered by the parent GuiObject. The appearance of the gradient is configurable through the following properties:
- Rotation, a number
A UIGradient will not apply to child or descendant GuiObjects. In order to apply the the same gradient to multiple objects, you will need multiple UIGradients.
Supported Objects
You can apply gradients to Frame, TextLabel, TextButton, ImageLabel, ImageButton, and ViewportFrame. However, ScrollingFrame and TextBox are not currently supported.
Performance Considerations
In order to efficiently use a UIGradient, follow these principles:
- Avoid using more than 6 color stops on the Color sequence.
- Avoid using a UIGradient on any object that applies a text stroke (TextStrokeColor3): the gradient will try to blend with strokes and borders, and may cause performance issues.
- Avoid setting Color and Transparency frequently: this causes the sequence of colors to rebuild often, which is expensive. If possible, set these properties only once and try to animate the Offset or Rotation properties to achieve a similar effect. Alternatively, you can change the color of the parent GuiObject using such properties as BackgroundColor3, ImageColor3, or TextColor3.
- When applying an unchanging gradient on a UI element whose state changes a lot, there is a trade-off between using a UIGradient (processing time) and a static gradient image (memory).
See also:
- UI Layout and Appearance for more information on creating UIGradient objects and how they work.
Summary
Properties
Determines the color blended with the parent GuiObject along the length of the gradient.
Determines the scalar translation of the gradient from the center of the parent GuiObject.
Determines the clockwise rotation in degrees of the gradient starting from left to right.
Determines how much the parent GuiObject can be seen through along the length of the gradient.
Events
Methods
Properties
Color
The Color of a UIGradient describes the color to blend with the parent UI element along the provided ColorSequence. This property works in a similar manner to Beam.Color or Trail.Color, except that it applies over an on-screen distance determined by the Offset and Rotation of the UIGradient. The image below shows the linear interpolation of four color values:
Enabled
Whether the gradient is enabled or not.
Offset
The Offset of a UIGradient determines the scalar translation of the gradient from the center of the parent GuiObject. This value is a scalar translation, meaning that the actual pixel offset is determined by the AbsoluteSize of the parent GuiObject. So, a value of (1, 0) would shift the gradient horizontally to the right by a distance equal to the parent GuiObject's on screen-size. Depending on the Rotation, this may cause the gradient to be partially visible or not visible at all.
In the animation above, the offset of a UIGradient is animated back and forth between the values (-1, 0) and (1, 0). The red dot indicates the start of the gradient, and the blue dot indicates the end. Note how the distance animated is twice that of the frame's width, as the offset is scalar.
Also see UIGradient.Rotation, which also affects the geometry of the applied gradient.
Rotation
The Rotation determines the clockwise rotation in degrees of the UIGradient starting from left to right. The beginning and end control points snap to the edges of the parent GuiObject, but maintain the provided rotation.
The animation above shows the snapping behavior of the gradient control points. The red indicates the start point, and the blue indicates the end. Although the control points do not move at a constant pace, the angle between them changes at a constant pace.
Also see UIGradient.Offset, which also affects the geometry of the applied gradient
Transparency
The Transparency of a UIGradient describes how "see-through" the parent UI element will be along the provided NumberSequence. This property works in a similar manner to Beam.Transparency or Trail.Transparency, except that it applies over an on-screen distance determined by the Offset and Rotation of the UIGradient. The image below shows the linear interpolation of three transparency values:
Note: the envelope values of the NumberSequenceKeypoints are ignored.