# 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: TextService
type: class
memory_category: Instances
summary: |
  Service internally responsible for handling the display of text.
description: |
  `TextService` is internally responsible for handling the display of text.
code_samples: []
inherits:
  - Instance
descendants: []
tags:
  - NotCreatable
  - Service
  - NotReplicated
deprecation_message: ''
properties: []
methods:
  - name: TextService:FilterAndTranslateStringAsync
    summary: |
      Filters and translates a string.
    description: |
      This method is no longer supported and should not be used. Translating
      chat messages is only available via `Class.TextChatService`.
    code_samples: []
    parameters:
      - name: stringToFilter
        type: string
        default:
        summary: ''
      - name: fromUserId
        type: int64
        default:
        summary: ''
      - name: targetLocales
        type: Array
        default:
        summary: ''
      - name: textContext
        type: TextFilterContext
        default: PrivateChat
        summary: ''
    returns:
      - type: TextFilterTranslatedResult
        summary: ''
    tags:
      - Yields
    deprecation_message: |
      This method is no longer supported and should not be used. All calls
      return an empty object.
    security: None
    thread_safety: Unsafe
    capabilities:
      - UI
  - name: TextService:FilterStringAsync
    summary: |
      Filters a string being received from a user and returns a
      `Class.TextFilterResult` which can be used to distribute the correctly
      filtered text accordingly.
    description: |
      This method filters a string being received from a user and returns a
      `Class.TextFilterResult` which can be used to distribute the correctly
      filtered text accordingly.

      This method should be called once each time a user submits a message. If
      it fails, do not display the text to any user.

      See [text filtering](../../../ui/text-filtering.md) for usage guidelines
      and examples.

      #### Notes

      - This method always yields to make a text filtering service call.
      - This method may throw if there is a service error that cannot be
        resolved. In such cases, do not retry the request, as this method
        implements its own retry logic internally.
      - This method currently throws if `fromUserId` is not online on the
        current server.
    code_samples: []
    parameters:
      - name: stringToFilter
        type: string
        default:
        summary: |
          The text to be filtered.
      - name: fromUserId
        type: int64
        default:
        summary: |
          The `Class.Player.UserId` of the player filtering the text.
      - name: textContext
        type: TextFilterContext
        default: PrivateChat
        summary: |
          The context that the filtered message will be used in. This parameter
          does not impact the filtered result of the query and is only used to
          improve Roblox's text filtering.
    returns:
      - type: TextFilterResult
        summary: ''
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - UI
  - name: TextService:GetFamilyInfoAsync
    summary: |
      Returns a table containing the name and faces of a font family.
    description: |
      Returns a table containing the name and faces of a font family. If the
      font family has already been loaded by a previous call to
      `GetFamilyInfoAsync()`, `Class.ContentProvider:PreloadAsync()`, or a text
      object with the `Class.TextLabel.FontFace` property set, then the method
      returns without yielding.

      This method can fail because of network errors and should be wrapped in
      `Global.LuaGlobals.pcall()` to catch and handle errors.
    code_samples:
      - TextService-GetFamilyInfoAsync-1
    parameters:
      - name: assetId
        type: ContentId
        default:
        summary: |
          Asset ID of the font family to look up.
    returns:
      - type: Dictionary
        summary: |
          The information about the font family.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - UI
  - name: TextService:GetTextBoundsAsync
    summary: |
      Computes the `Datatype.Vector2` dimensions (in pixels) that will be taken
      up with text when using a `Class.GetTextBoundsParams` object.
    description: |
      Computes the `Datatype.Vector2` dimensions (in pixels) that will be taken
      up with text when using parameters defined in a
      `Class.GetTextBoundsParams` object. This method is similar to
      `Class.TextService:GetTextSize()|GetTextSize()` but uses the
      `Datatype.Font` object which has access to more fonts than `Enum.Font`.

      This method is a useful alternative to the `TextBounds` property of the
      `Class.TextLabel`/`Class.TextButton` objects, since `GetTextBoundsAsync()`
      can calculate the dimensions required by a particular text string in a
      `Class.TextLabel` or `Class.TextButton` before such an object is created
      or text property set.

      This is a yielding method because some fonts may need to be loaded in
      order to measure them. As a result, it should be wrapped in
      `Global.LuaGlobals.pcall()` to catch and handle errors. If the font is
      already loaded, it will not yield; `Class.ContentProvider:PreloadAsync()`
      can be used to make sure a font is loaded.
    code_samples:
      - TextService-GetTextBoundsAsync-1
    parameters:
      - name: params
        type: GetTextBoundsParams
        default:
        summary: |
          A reference to a `Class.GetTextBoundsParams` object.
    returns:
      - type: Vector2
        summary: |
          The size of the text as a `Datatype.Vector2`.
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - UI
  - name: TextService:GetTextSize
    summary: |
      Computes the `Datatype.Vector2` dimensions (in pixels) that will be taken
      up with text when using the specified formatting parameters and size
      constraints.
    description: |
      Computes the `Datatype.Vector2` dimensions (in pixels) that will be taken
      up with text when using the specified formatting parameters and size
      constraints.

      This method is a useful alternative to the `TextBounds` property of the
      `Class.TextLabel`/`Class.TextButton` objects, since `GetTextSize()` can
      calculate the dimensions required by a particular text string in a
      `Class.TextLabel` or `Class.TextButton` before such an object is created
      or text property set.

      This method is limited to fonts under `Enum.Font`. To access more fonts
      under `Datatype.Font`, use
      `Class.TextService:GetTextBoundsAsync()|GetTextBoundsAsync()` instead.
    code_samples:
      - textservice-getting-the-text-size
    parameters:
      - name: string
        type: string
        default:
        summary: |
          The string for which the text size is to be calculated.
      - name: fontSize
        type: int
        default:
        summary: |
          The integer representing the font size used. Does not accept an
          `Enum.FontSize` value.
      - name: font
        type: Enum.Font
        default:
        summary: |
          The font used.
      - name: frameSize
        type: Vector2
        default:
        summary: |
          The `Class.GuiBase2d.AbsoluteSize` of the text object to be used.
          Required to compute how the text will wrap.
    returns:
      - type: Vector2
        summary: |
          The size of the space required, in pixels, by the string with the
          specified formatting.
    tags: []
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - UI
  - name: TextService:GetTextSizeOffsetAsync
    summary: |
      Returns the offset used to up-scale text based on the current
      `Class.GuiService.PreferredTextSize` setting.
    description: |
      Returns the offset used to up-scale text based on
      `Class.GuiService.PreferredTextSize`, a property which may change through
      the player's setting in the Roblox or in‑experience **Settings** menus.

      This offset can be used as an additive value to adjust the core height
      value of a `Class.TextLabel` or `Class.TextButton` based on
      `Class.GuiService.PreferredTextSize|PreferredTextSize`.

      Note that, currently, the `fontSize` and `font` parameters do not affect
      the outcome and this method returns merely the offset as described above.
      Also note that this method can fail because of network errors and should
      be wrapped in `Global.LuaGlobals.pcall()` to catch and handle errors.
    code_samples:
      - TextService-GetTextSizeOffsetAsync
    parameters:
      - name: fontSize
        type: int
        default:
        summary: ''
      - name: font
        type: Datatype.Font
        default:
        summary: ''
    returns:
      - type: float
        summary: ''
    tags:
      - Yields
    deprecation_message: ''
    security: None
    thread_safety: Unsafe
    capabilities:
      - UI
events: []
callbacks: []