class_docstr: An internal class to manage widgets.
  
  It also manages and other helper methods involving widgets.
class_docstr_tok: ["An","internal","class","to","manage","widgets",".","It","also","manages","and","other","helper","methods","involving","widgets","."]
docstr: Add a checkbox button widget to the scene.
  
  This is useless without a callback function. You can pass a callable
  function that takes a single argument, the state of this button widget
  and performs a task with that value.
  
  Parameters
  ----------
  callback : callable
      The method called every time the button is clicked. This should take
      a single parameter: the bool value of the button.
  
  value : bool, default: False
      The default state of the button.
  
  position : sequence[float], default: (10.0, 10.0)
      The absolute coordinates of the bottom left point of the button.
  
  size : int, default: 50
      The size of the button in number of pixels.
  
  border_size : int, default: 5
      The size of the borders of the button in pixels.
  
  color_on : ColorLike, optional
      The color used when the button is checked. Default is ``'blue'``.
  
  color_off : ColorLike, optional
      The color used when the button is not checked. Default is ``'grey'``.
  
  background_color : ColorLike, optional
      The background color of the button. Default is ``'white'``.
  
  Returns
  -------
  vtk.vtkButtonWidget
      The VTK button widget configured as a checkbox button.
  
  Examples
  --------
  The following example generates a static image of the widget.
  
  >>> import pyvista as pv
  >>> mesh = pv.Sphere()
  >>> p = pv.Plotter()
  >>> actor = p.add_mesh(mesh)
  >>> def toggle_vis(flag):
  ...     actor.SetVisibility(flag)
  ...
  >>> _ = p.add_checkbox_button_widget(toggle_vis, value=True)
  >>> p.show()
  
  Download the interactive example at :ref:`checkbox_widget_example`.
docstr_tok: ["Add","a","checkbox","button","widget","to","the","scene",".","This","is","useless","without","a","callback","function",".","You","can","pass","a","callable","function","that","takes","a","single","argument",",","the","state","of","this","button","widget","and","performs","a","task","with","that","value",".","Parameters","--","--","--","--","--","callback",":","callable","The","method","called","every","time","the","button","is","clicked",".","This","should","take","a","single","parameter",":","the","bool","value","of","the","button",".","value",":","bool",",","default",":","False","The","default","state","of","the","button",".","position",":","sequence","[","float","]",",","default",":","(","10.0",",","10.0",")","The","absolute","coordinates","of","the","bottom","left","point","of","the","button",".","size",":","int",",","default",":","50","The","size","of","the","button","in","number","of","pixels",".","border_size",":","int",",","default",":","5","The","size","of","the","borders","of","the","button","in","pixels",".","color_on",":","ColorLike",",","optional","The","color","used","when","the","button","is","checked",".","Default","is","``","'blue","'","``",".","color_off",":","ColorLike",",","optional","The","color","used","when","the","button","is","not","checked",".","Default","is","``","'grey","'","``",".","background_color",":","ColorLike",",","optional","The","background","color","of","the","button",".","Default","is","``","'white","'","``",".","Returns","--","--","--","-","vtk.vtkButtonWidget","The","VTK","button","widget","configured","as","a","checkbox","button",".","Examples","--","--","--","--","The","following","example","generates","a","static","image","of","the","widget",".",">",">",">","import","pyvista","as","pv",">",">",">","mesh","=","pv.Sphere","(",")",">",">",">","p","=","pv.Plotter","(",")",">",">",">","actor","=","p.add_mesh","(","mesh",")",">",">",">","def","toggle_vis","(","flag",")",":","...","actor.SetVisibility","(","flag",")","...",">",">",">","_","=","p.add_checkbox_button_widget","(","toggle_vis",",","value=True",")",">",">",">","p.show","(",")","Download","the","interactive","example","at",":","ref",":","`","checkbox_widget_example","`","."]
code: def add_checkbox_button_widget(
      self,
      callback,
      value=False,
      position=(10.0, 10.0),
      size=50,
      border_size=5,
      color_on="blue",
      color_off="grey",
      background_color="white",
  ):
      """Add a checkbox button widget to the scene.
  
      This is useless without a callback function. You can pass a callable
      function that takes a single argument, the state of this button widget
      and performs a task with that value.
  
      Parameters
      ----------
      callback : callable
          The method called every time the button is clicked. This should take
          a single parameter: the bool value of the button.
  
      value : bool, default: False
          The default state of the button.
  
      position : sequence[float], default: (10.0, 10.0)
          The absolute coordinates of the bottom left point of the button.
  
      size : int, default: 50
          The size of the button in number of pixels.
  
      border_size : int, default: 5
          The size of the borders of the button in pixels.
  
      color_on : ColorLike, optional
          The color used when the button is checked. Default is ``'blue'``.
  
      color_off : ColorLike, optional
          The color used when the button is not checked. Default is ``'grey'``.
  
      background_color : ColorLike, optional
          The background color of the button. Default is ``'white'``.
  
      Returns
      -------
      vtk.vtkButtonWidget
          The VTK button widget configured as a checkbox button.
  
      Examples
      --------
      The following example generates a static image of the widget.
  
      >>> import pyvista as pv
      >>> mesh = pv.Sphere()
      >>> p = pv.Plotter()
      >>> actor = p.add_mesh(mesh)
      >>> def toggle_vis(flag):
      ...     actor.SetVisibility(flag)
      ...
      >>> _ = p.add_checkbox_button_widget(toggle_vis, value=True)
      >>> p.show()
  
      Download the interactive example at :ref:`checkbox_widget_example`.
  
      """
      if self.iren is None:  # pragma: no cover
          raise RuntimeError("Cannot add a widget to a closed plotter.")
  
      def create_button(
          color1, color2, color3, dims=(size, size, 1)
      ):  # numpydoc ignore=GL08
          color1 = np.array(Color(color1).int_rgb)
          color2 = np.array(Color(color2).int_rgb)
          color3 = np.array(Color(color3).int_rgb)
  
          n_points = dims[0] * dims[1]
          button = pyvista.ImageData(dimensions=dims)
          arr = np.array([color1] * n_points).reshape(
              dims[0], dims[1], 3
          )  # fill with color1
          arr[1 : dims[0] - 1, 1 : dims[1] - 1] = color2  # apply color2
          arr[
              border_size : dims[0] - border_size,
              border_size : dims[1] - border_size,
          ] = color3  # apply color3
          button.point_data["texture"] = arr.reshape(
              n_points, 3
          ).astype(np.uint8)
          return button
  
      button_on = create_button(color_on, background_color, color_on)
      button_off = create_button(color_on, background_color, color_off)
  
      bounds = [
          position[0],
          position[0] + size,
          position[1],
          position[1] + size,
          0.0,
          0.0,
      ]
  
      button_rep = _vtk.vtkTexturedButtonRepresentation2D()
      button_rep.SetNumberOfStates(2)
      button_rep.SetState(value)
      button_rep.SetButtonTexture(0, button_off)
      button_rep.SetButtonTexture(1, button_on)
      button_rep.SetPlaceFactor(1)
      button_rep.PlaceWidget(bounds)
  
      button_widget = _vtk.vtkButtonWidget()
      button_widget.SetInteractor(self.iren.interactor)
      button_widget.SetRepresentation(button_rep)
      button_widget.SetCurrentRenderer(self.renderer)
      button_widget.On()
  
      def _the_callback(widget, _event):
          state = widget.GetRepresentation().GetState()
          if callable(callback):
              try_callback(callback, bool(state))
  
      button_widget.AddObserver(
          _vtk.vtkCommand.StateChangedEvent, _the_callback
      )
      self.button_widgets.append(button_widget)
      return button_widget
  
imports: import pathlib
  from typing import Optional, Sequence, Tuple, Union
  import numpy
  import pyvista
  from pyvista.core.utilities.arrays import get_array, get_array_association
  from pyvista.core.utilities.geometric_objects import NORMALS
  from pyvista.core.utilities.helpers import generate_plane
  from pyvista.core.utilities.misc import assert_empty_kwargs, try_callback
  from .None import _vtk
  from .affine_widget import AffineWidget3D
  from .colors import Color
  from .opts import PickerType
  from .utilities.algorithms import add_ids_algorithm, algorithm_to_mesh_handler, crinkle_algorithm, outline_algorithm, pointset_to_polydata_algorithm, set_algorithm_input
label_desc: Use image node_id 26 for calling the WidgetHelper obj's underlying member method code with example usage: obj.add_checkbox_button_widget(callback, value, position, size, border_size, color_on, color_off, background_color) and returns: button_widget, button