# 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: PluginToolbarButton
type: class
memory_category: Instances
summary: ''
description: |
  A `PluginToolbarButton` object is created through the
  `Class.PluginToolbar:CreateButton()` function. It allows the user to initiate
  a single, one-off action in Roblox Studio through the
  `Class.PluginToolbarButton.Click|Click` event. Toolbar buttons can also be
  assigned a keyboard shortcut through Studio's **File** ⟩ **Customize
  Shortcuts** window.

  When pressed, the `Class.PluginToolbarButton.Click|Click` event fires. A
  button will also remain in the pressed state, which may be set manually using
  `Class.PluginToolbarButton:SetActive()|SetActive()`. Upon plugin activation
  (`Class.Plugin:Activate()`), buttons in all other
  `Class.PluginToolbar|PluginToolbars` will be toggled off. If all buttons in a
  toolbar are off, the toolbar's plugin is deactivated
  (`Class.Plugin:Deactivate()`).

  When the game viewport is not visible, buttons will be disabled as if their
  `Class.PluginToolbarButton.Enabled|Enabled` property were false. Disabled
  buttons are desaturated and do not respond to user clicks. By setting
  `Class.PluginToolbarButton.ClickableWhenViewportHidden|ClickableWhenViewportHidden`
  to true, you can allow plugin buttons to remain clickable, such as during
  script editing.
code_samples: []
inherits:
  - Instance
descendants: []
tags:
  - NotCreatable
deprecation_message: ''
properties:
  - name: PluginToolbarButton.ClickableWhenViewportHidden
    summary: |
      Determines whether the button can be clicked when the 3D viewport is
      hidden, such as when a `Class.Script` is being edited in another tab.
    description: |
      This property determines whether a `Class.PluginToolbarButton` may be
      clicked while the 3D viewport is hidden, such as when a `Class.Script` is
      being edited in another tab.

      Typically, this property should be enabled if an action triggered by a
      plugin button's `Class.PluginToolbarButton.Click|Click` event doesn't
      occur in the 3D world (`Class.Workspace`). For example, a button that
      opens a widget should have this property as `true`, since showing a widget
      is visible to the user even if the 3D view isn't visible.
    code_samples: []
    type: boolean
    tags:
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: false
    capabilities: []
  - name: PluginToolbarButton.Enabled
    summary: |
      Determines whether the button is clickable in general.
    description: |
      This property determines whether a button is clickable in general. When
      `false`, the button will be greyed out and unclickable, preventing the
      user from firing the `Class.PluginToolbarButton.Click|Click` event.
      Buttons are enabled by default.

      When re-enabling this property, the plugin button's state won't be
      remembered from the previous state in which the user left the button in.
      Instead, it will default to the last state set by
      `Class.PluginToolbarButton:SetActive()|SetActive()` or to the inactive
      state if `Class.PluginToolbarButton:SetActive()|SetActive()` was never
      used.

      Plugins should disable their buttons when the button action isn't relevant
      in the current context. For example, a plugin button that assigns random
      colors to selected should not be enabled when the selection contains no
      parts.

      See also
      `Class.PluginToolbarButton.ClickableWhenViewportHidden|ClickableWhenViewportHidden`
      which determines whether a button is clickable when the game view is
      hidden (and not just in general).
    code_samples:
      - brickcolor-randomizer-plugin
    type: boolean
    tags:
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: false
    capabilities: []
  - name: PluginToolbarButton.Icon
    summary: |
      Determines what icon should represent the button.
    description: |
      This property determines which `Datatype.Content` should be shown for the
      button's icon in the toolbar. When this property is not set, the button
      will instead use the button's text given by
      `Class.PluginToolbar:CreateButton()`.
    code_samples: []
    type: ContentId
    tags:
      - NotReplicated
    deprecation_message: ''
    security:
      read: None
      write: None
    thread_safety: ReadSafe
    category: Appearance
    serialization:
      can_load: true
      can_save: false
    capabilities: []
methods:
  - name: PluginToolbarButton:SetActive
    summary: |
      Sets the state of the plugin button.
    description: |
      This method can be used to manually set the active state of the plugin
      button.

      When the `Class.PluginToolbarButton.Enabled|Enabled` property is toggled
      back on, the button will either revert to the last state set by this
      method or default to inactive if this method hasn't been used previously.
    code_samples: []
    parameters:
      - name: active
        type: boolean
        default:
        summary: ''
    returns:
      - type: ()
        summary: ''
    tags: []
    deprecation_message: ''
    security: PluginSecurity
    thread_safety: Unsafe
    capabilities: []
events:
  - name: PluginToolbarButton.Click
    summary: |
      Fires when the user presses and releases their cursor on the button.
    description: |
      This event fires when the `Class.PluginToolbarButton` is pressed and
      released by the user.

      See also `Class.PluginToolbarButton:SetActive()|SetActive()` to manually
      set the state of the button.
    code_samples:
      - plugintoolbarbutton-click
    parameters: []
    tags: []
    deprecation_message: ''
    security: PluginSecurity
    capabilities: []
callbacks: []