rules

.cursor/rules/roblox/reference/engine/classes/TextButton.yaml

@@ -0,0 +1,727 @@
+# This file is automatically generated. Please don't edit it manually.
+# To submit a bug report on the content, see
+# https://devforum.roblox.com/c/bug-reports/documentation-issues/72
+
+name: TextButton
+type: class
+memory_category: Gui
+summary: |
+  A 2D user interface element that displays interactive text.
+description: |
+  A `Class.TextButton` behaves similarly to `Class.TextLabel` in regards to
+  rendering, with the additional behaviors of a `Class.GuiButton`.
+
+  You can disable text rendering by setting
+  `Class.TextButton.TextTransparency|TextTransparency` to `1`. This will result
+  in a plain rectangle that can be used as a button.
+code_samples: []
+inherits:
+  - GuiButton
+descendants: []
+tags: []
+deprecation_message: ''
+properties:
+  - name: TextButton.ContentText
+    summary: |
+      A copy of `Class.TextButton.Text` that contains exactly what is being
+      rendered by the `Class.TextButton`.
+    description: |
+      This property provides a copy of `Class.TextButton.Text|Text` that
+      contains exactly what is being rendered by the `Class.TextButton`. This is
+      useful for eliminating style tags used for
+      [rich text](../../../ui/rich-text.md) markup; for example, when
+      `Class.TextButton.RichText|RichText` is enabled, the
+      `Class.TextButton.ContentText|ContentText` property shows the text as it
+      appears to the user.
+
+      <table>
+          <thead>
+              <tr>
+                  <th>RichText</th>
+                  <th>Text</th>
+                  <th>ContentText</th>
+              </tr>
+          </thead>
+          <tbody>
+              <tr>
+                  <td><code>false</code></td>
+                  <td>&lt;b&gt;Hello,&lt;br/&gt; world!&lt;/b&gt;</td>
+                  <td>&lt;b&gt;Hello,&lt;br/&gt; world!&lt;/b&gt;</td>
+              </tr>
+              <tr>
+                  <td><code>true</code></td>
+                  <td>&lt;b&gt;Hello,&lt;br/&gt; world!&lt;/b&gt;</td>
+                  <td>Hello,<br/> world!</td>
+              </tr>
+          </tbody>
+        </table>
+    code_samples: []
+    type: string
+    tags:
+      - ReadOnly
+      - NotReplicated
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: false
+      can_save: false
+    capabilities:
+      - UI
+  - name: TextButton.Font
+    summary: |
+      Determines the font used to render text.
+    description: |
+      This property selects one of several pre-defined fonts with which the
+      `Class.TextButton` will render its text. Some fonts have bold, italic
+      and/or light variants.
+
+      With the exception of the `Enum.Font.Legacy` font, each font will render
+      text with the line height equal to the
+      `Class.TextButton.TextSize|TextSize` property.
+
+      The `Enum.Font.Code` font is the only monospace font. It has the unique
+      property that each character has the exact same width and height ratio of
+      1:2, where the width of each character is approximately half the
+      `Class.TextButton.TextSize|TextSize` property.
+
+      This property is kept in sync with the
+      `Class.TextButton.FontFace|FontFace` property.
+    code_samples:
+      - Show-All-Fonts
+    type: Enum.Font
+    tags:
+      - Hidden
+      - NotReplicated
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: false
+    capabilities:
+      - UI
+  - name: TextButton.FontFace
+    summary: |
+      Determines the font used to render text.
+    description: |
+      This property is similar to the `Class.TextButton.Font|Font` property but
+      allows setting fonts that don't exist in `Enum.Font`.
+
+      This property is kept in sync with the `Class.TextButton.Font|Font`
+      property, such that when setting `Class.TextButton.FontFace|FontFace`, the
+      font is set to the corresponding `Enum.Font` value or to
+      `Enum.Font.Unknown` if there are no matches.
+    code_samples: []
+    type: Datatype.Font
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.FontSize
+    summary: |
+      Determines the font size to be used.
+    description: |
+      This property determines the font size to be used.
+    code_samples: []
+    type: FontSize
+    tags:
+      - NotReplicated
+      - Deprecated
+    deprecation_message: |
+      This property is deprecated in favor of `Class.TextButton|TextSize` which
+      is an integer and not an enum and thus offers far more options for sizes.
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: false
+    capabilities:
+      - UI
+  - name: TextButton.LineHeight
+    summary: |
+      Scales the spacing between lines of text in the `Class.TextButton`.
+    description: |
+      Controls the height of lines as a multiple of the font's `em` square size
+      by scaling the spacing between lines of text in the `Class.TextButton`.
+      Valid values range from `1.0` to `3.0`, defaulting to `1.0`.
+    code_samples: []
+    type: float
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.LocalizedText
+    summary: |
+      Sets whether a `Class.TextButton` should be `Class.GuiBase2d.Localize` or
+      not.
+    description: |
+      This property sets whether a `Class.TextButton` should regard
+      `Class.GuiBase2d.Localize` or not.
+    code_samples: []
+    type: string
+    tags:
+      - Hidden
+      - ReadOnly
+      - NotReplicated
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Data
+    serialization:
+      can_load: false
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.MaxVisibleGraphemes
+    summary: |
+      The maximum number of graphemes the `Class.TextButton` can show.
+    description: |
+      This property controls the maximum number of graphemes (or units of text)
+      that are shown on the `Class.TextButton`. It is primarily provided as an
+      easy way to create a
+      [typewriter effect](../../../ui/animation.md#typewriter-effect) where the
+      characters appear one at a time.
+
+      Changing the property does not change the position or size of the visible
+      graphemes; the layout will be calculated as if all graphemes are visible.
+
+      Setting the property to `-1` disables the limit and shows the entirety of
+      the `Class.TextButton.Text|Text`.
+    code_samples: []
+    type: int
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.OpenTypeFeatures
+    summary: ''
+    description: ''
+    code_samples: []
+    type: string
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.OpenTypeFeaturesError
+    summary: ''
+    description: ''
+    code_samples: []
+    type: string
+    tags:
+      - ReadOnly
+      - NotReplicated
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: false
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.RichText
+    summary: |
+      Determines whether the `Class.TextButton` renders its text using rich text
+      formatting.
+    description: |
+      This property determines whether the `Class.TextButton` renders its text
+      using [rich text](../../../ui/rich-text.md) markup to style sections of
+      the string in bold, italics, specific colors, and more.
+
+      To use rich text, simply include rich text formatting tags in the
+      `Class.TextButton.Text|Text` string.
+    code_samples: []
+    type: boolean
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.Text
+    summary: |
+      Determines the string rendered by the `Class.TextButton`.
+    description: |
+      This property determines the text content rendered by the
+      `Class.TextButton`. The visual properties of the string rendered to the
+      screen is determined by `Class.TextButton.TextColor3|TextColor3`,
+      `Class.TextButton.TextTransparency|TextTransparency`,
+      `Class.TextButton.TextSize|TextSize`, `Class.TextButton.Font|Font`,
+      `Class.TextButton.TextScaled|TextScaled`,
+      `Class.TextButton.TextWrapped|TextWrapped`,
+      `Class.TextButton.TextXAlignment|TextXAlignment` and
+      `Class.TextButton.TextYAlignment|TextYAlignment`.
+
+      It is possible to render emoji such as 🔒 and other symbols which aren't
+      affected by the `Class.TextButton.TextColor3|TextColor3` property. These
+      can be pasted into `Class.Script` and `Class.LocalScript` objects, as well
+      as the field within the [Properties](../../../studio/properties.md)
+      window.
+
+      This property may contain newline characters. Similarly, this property may
+      contain a tab character, but it will render as a space instead.
+    code_samples:
+      - Fading-Banner
+      - Emoji-in-Text
+    type: string
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.TextBounds
+    summary: |
+      Read-only property which reflects the absolute size of rendered text in
+      offsets.
+    description: |
+      This read-only property reflects the absolute size of rendered text in
+      offsets, meaning that if you try to fit text into a rectangle, this
+      property would reflect the minimum dimensions of the rectangle you'd need
+      in order to fit the text.
+
+      Using `Class.TextService:GetTextSize()`, you can predict what
+      `Class.TextButton.TextBounds|TextBounds` will be given a string,
+      `Class.TextButton.Font|Font`, `Class.TextButton.TextSize|TextSize`, and
+      frame size.
+    code_samples: []
+    type: Vector2
+    tags:
+      - ReadOnly
+      - NotReplicated
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: false
+      can_save: false
+    capabilities:
+      - UI
+  - name: TextButton.TextColor
+    summary: |
+      Determines the color of text.
+    description: |
+      This property determines the color of text.
+    code_samples: []
+    type: BrickColor
+    tags:
+      - Hidden
+      - NotReplicated
+      - Deprecated
+    deprecation_message: |
+      This item has been superseded by `Class.TextButton.TextColor3` which
+      should be used in all new work.
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: false
+    capabilities:
+      - UI
+  - name: TextButton.TextColor3
+    summary: |
+      Determines the color of rendered text.
+    description: |
+      This property determines the color of all the text rendered by the
+      `Class.TextButton` element.
+    code_samples:
+      - Countdown-Text
+    type: Color3
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.TextDirection
+    summary: |
+      Direction in which the text is rendered.
+    description: |
+      `Enum.TextDirection` in which the text is rendered.
+    code_samples: []
+    type: TextDirection
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.TextFits
+    summary: |
+      A boolean representation of whether the button's text fits within the size
+      of it.
+    description: |
+      A boolean representation of whether the button's text fits within the size
+      of it.
+    code_samples: []
+    type: boolean
+    tags:
+      - ReadOnly
+      - NotReplicated
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: false
+      can_save: false
+    capabilities:
+      - UI
+  - name: TextButton.TextScaled
+    summary: |
+      Changes whether text is resized to fit within the `Class.TextButton`.
+    description: |
+      This property determines whether text is scaled so that it fills the
+      button's entire space. When enabled, `Class.TextButton.TextSize|TextSize`
+      is ignored and `Class.TextButton.TextWrapped|TextWrapped` is automatically
+      enabled. This property is useful for rendering text elements within
+      `Class.BillboardGui|BillboardGuis`. When this property is used for
+      [on-screen UI](../../../ui/on-screen-containers.md), it may be helpful to
+      use a `Class.UITextSizeConstraint` to restrict the range of possible text
+      sizes.
+
+      ##### Automatic Sizing
+
+      It's recommended that you avoid usage of
+      `Class.TextButton.TextScaled|TextScaled` and adjust UI to take advantage
+      of the `Class.GuiObject.AutomaticSize|AutomaticSize` property instead.
+      Here are the core differences between the two properties:
+
+      - `Class.TextButton.TextScaled|TextScaled` scales the content (text) to
+        accommodate the UI. Without careful consideration, some text may become
+        unreadable if scaled too small.
+
+      - `Class.GuiObject.AutomaticSize|AutomaticSize` resizes the UI to
+        accommodate content while maintaining a consistent font size. For more
+        information, see [here](../../../ui/size-modifiers.md#automatic-sizing).
+
+      Additionally, it's recommended that you avoid applying both
+      `Class.GuiObject.AutomaticSize|AutomaticSize` and
+      `Class.TextButton.TextScaled|TextScaled` and to the same
+      `Class.TextButton`. `Class.GuiObject.AutomaticSize|AutomaticSize`
+      determines the maximum amount of available space that a `Class.GuiObject`
+      can use (in this case, text), while
+      `Class.TextButton.TextScaled|TextScaled` uses the available space
+      determined by `Class.GuiObject.AutomaticSize|AutomaticSize` to scale the
+      font size up to the maximum font size (100) if there are no size
+      constraints.
+    code_samples: []
+    type: boolean
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.TextSize
+    summary: |
+      Determines the line height of text in offsets.
+    description: |
+      This property determines the height of one line of rendered text. The unit
+      is in offsets, not points (which is used in most document editing
+      programs). The `Enum.Font.Legacy` font does not hold this property.
+    code_samples: []
+    type: float
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.TextStrokeColor3
+    summary: |
+      Determines the color of the text stroke (outline).
+    description: |
+      This property sets the color of the stroke, or outline, of rendered text.
+      Along with
+      `Class.TextButton.TextStrokeTransparency|TextStrokeTransparency`, it
+      determines the final visual appearance of the text stroke.
+
+      As a powerful alternative which supports color gradients, see
+      `Class.UIStroke`.
+    code_samples: []
+    type: Color3
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.TextStrokeTransparency
+    summary: |
+      Determines the transparency of the text stroke (outline).
+    description: |
+      This property sets the transparency of the stroke, or outline, of rendered
+      text. Along with `Class.TextButton.TextStrokeColor3|TextStrokeColor3`, it
+      determines the final visual appearance of the text stroke.
+
+      Note that text stroke is multiple renderings of the same transparency, so
+      this property is essentially multiplicative on itself four times over.
+      Therefore, it's recommended to set
+      `Class.TextButton.TextStrokeTransparency|TextStrokeTransparency` to a
+      value in the range of `0.75` to `1` for more a more subtle effect.
+
+      As a powerful alternative which supports color gradients, see
+      `Class.UIStroke`.
+    code_samples: []
+    type: float
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.TextTransparency
+    summary: |
+      Determines the transparency of rendered text.
+    description: |
+      This property determines the transparency of all the text rendered by the
+      `Class.TextButton`.
+    code_samples: []
+    type: float
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.TextTruncate
+    summary: |
+      Controls the truncation of the text displayed in the `Class.TextButton`.
+    description: |
+      Controls the truncation of the text displayed in the `Class.TextButton`.
+    code_samples: []
+    type: TextTruncate
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.TextWrap
+    summary: |
+      Determines whether or not text should wrap at the edges of the
+      `Class.TextButton` element's space.
+    description: |
+      This property determines whether or not text should wrap at the edges of
+      the `Class.TextButton` element's space.
+    code_samples: []
+    type: boolean
+    tags:
+      - NotReplicated
+      - Deprecated
+    deprecation_message: |
+      This item has been superseded by `Class.TextButton.TextWrapped` which
+      should be used in all new work.
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: false
+    capabilities:
+      - UI
+  - name: TextButton.TextWrapped
+    summary: |
+      Determines if text wraps to multiple lines within the `Class.TextButton`
+      element's space, truncating excess text.
+    description: |
+      When enabled, this property will render text on multiple lines within a
+      `Class.TextButton` element's space so that
+      `Class.TextButton.TextBounds|TextBounds` will never exceed the
+      `Class.GuiBase2d.AbsoluteSize` of the element. This is achieved by
+      breaking long lines of text into multiple lines.
+
+      Line breaks will prefer whitespace; should a long unbroken word exceed the
+      width of the element, that word will be broken into multiple lines.
+
+      If further line breaks would cause the vertical height of the text (the
+      **Y** component of `Class.TextButton.TextBounds|TextBounds`) to exceed the
+      vertical height of the element (the **Y** component of
+      `Class.GuiBase2d.AbsoluteSize`), then that line will not be rendered at
+      all.
+    code_samples: []
+    type: boolean
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.TextXAlignment
+    summary: |
+      Determines the horizontal alignment of rendered text.
+    description: |
+      This property determines the horizontal alignment of text rendered within
+      the object's space. It is used in conjunction with
+      `Class.TextButton.TextYAlignment|TextYAlignment` to fully determine text
+      alignment on both axes.
+
+      Note that this property won't affect the read-only properties
+      `Class.TextButton.TextBounds|TextBounds` and
+      `Class.TextButton.TextFits|TextFits`.
+    code_samples: []
+    type: TextXAlignment
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+  - name: TextButton.TextYAlignment
+    summary: |
+      Determines the vertical alignment of rendered text.
+    description: |
+      This property determines the vertical alignment of text rendered within
+      the object's space. It is used in conjunction with
+      `Class.TextButton.TextXAlignment|TextXAlignment` to fully determine text
+      alignment on both axes.
+
+      Note that this property won't affect the read-only properties
+      `Class.TextButton.TextBounds|TextBounds` and
+      `Class.TextButton.TextFits|TextFits`.
+    code_samples: []
+    type: TextYAlignment
+    tags: []
+    deprecation_message: ''
+    security:
+      read: None
+      write: None
+    thread_safety: ReadSafe
+    category: Text
+    serialization:
+      can_load: true
+      can_save: true
+    capabilities:
+      - UI
+methods: []
+events: []
+callbacks: []