class_docstr: The layout for a prompt_toolkit
  :class:`~prompt_toolkit.application.Application`.
  This also keeps track of which user control is focused.
  
  :param container: The "root" container for the layout.
  :param focused_element: element to be focused initially. (Can be anything
      the `focus` function accepts.)
class_docstr_tok: ["The","layout","for","a","prompt_toolkit",":","class",":","`","~prompt_toolkit.application.Application","`",".","This","also","keeps","track","of","which","user","control","is","focused",".",":","param","container",":","The","``","root","''","container","for","the","layout",".",":","param","focused_element",":","element","to","be","focused","initially",".","(","Can","be","anything","the","`","focus","`","function","accepts",".",")"]
docstr: Focus the given UI element.
  
  `value` can be either:
  
  - a :class:`.UIControl`
  - a :class:`.Buffer` instance or the name of a :class:`.Buffer`
  - a :class:`.Window`
  - Any container object. In this case we will focus the :class:`.Window`
    from this container that was focused most recent, or the very first
    focusable :class:`.Window` of the container.
docstr_tok: ["Focus","the","given","UI","element",".","`","value","`","can","be","either",":","-","a",":","class",":","`",".UIControl","`","-","a",":","class",":","`",".Buffer","`","instance","or","the","name","of","a",":","class",":","`",".Buffer","`","-","a",":","class",":","`",".Window","`","-","Any","container","object",".","In","this","case","we","will","focus","the",":","class",":","`",".Window","`","from","this","container","that","was","focused","most","recent",",","or","the","very","first","focusable",":","class",":","`",".Window","`","of","the","container","."]
code: def focus(self, value: FocusableElement) -> None:
      """
      Focus the given UI element.
  
      `value` can be either:
  
      - a :class:`.UIControl`
      - a :class:`.Buffer` instance or the name of a :class:`.Buffer`
      - a :class:`.Window`
      - Any container object. In this case we will focus the :class:`.Window`
        from this container that was focused most recent, or the very first
        focusable :class:`.Window` of the container.
      """
      # BufferControl by buffer name.
      if isinstance(value, str):
          for control in self.find_all_controls():
              if (
                  isinstance(control, BufferControl)
                  and control.buffer.name == value
              ):
                  self.focus(control)
                  return
          raise ValueError(
              f"Couldn't find Buffer in the current layout: {value!r}."
          )
  
      # BufferControl by buffer object.
      elif isinstance(value, Buffer):
          for control in self.find_all_controls():
              if (
                  isinstance(control, BufferControl)
                  and control.buffer == value
              ):
                  self.focus(control)
                  return
          raise ValueError(
              f"Couldn't find Buffer in the current layout: {value!r}."
          )
  
      # Focus UIControl.
      elif isinstance(value, UIControl):
          if value not in self.find_all_controls():
              raise ValueError(
                  "Invalid value. Container does not appear in the layout."
              )
          if not value.is_focusable():
              raise ValueError(
                  "Invalid value. UIControl is not focusable."
              )
  
          self.current_control = value
  
      # Otherwise, expecting any Container object.
      else:
          value = to_container(value)
  
          if isinstance(value, Window):
              # This is a `Window`: focus that.
              if value not in self.find_all_windows():
                  raise ValueError(
                      f"Invalid value. Window does not appear in the layout: {value!r}"
                  )
  
              self.current_window = value
          else:
              # Focus a window in this container.
              # If we have many windows as part of this container, and some
              # of them have been focused before, take the last focused
              # item. (This is very useful when the UI is composed of more
              # complex sub components.)
              windows = []
              for c in walk(value, skip_hidden=True):
                  if isinstance(c, Window) and c.content.is_focusable():
                      windows.append(c)
  
              # Take the first one that was focused before.
              for w in reversed(self._stack):
                  if w in windows:
                      self.current_window = w
                      return
  
              # None was focused before: take the very first focusable window.
              if windows:
                  self.current_window = windows[0]
                  return
  
              raise ValueError(
                  f"Invalid value. Container cannot be focused: {value!r}"
              )
  
imports: from __future__ import annotations
  from typing import Generator, Iterable, Union
  from prompt_toolkit.buffer import Buffer
  from .containers import AnyContainer, ConditionalContainer, Container, Window, to_container
  from .controls import BufferControl, SearchBufferControl, UIControl
label_desc: Use image node_id 5 for calling the Layout obj's underlying member method code with example usage: obj.focus(value) without return types