docs: def _qteFocusManager(self):
          """
          Give the focus to the correct applet and widget.
  
          This method is the only method in all of Qtmacs that actually
          instructs the Qt library to focus a widget. It does so by
          first synchronising what Qtmacs thinks is visible and what Qt
          knows is visible, and then make the applet/widget active for
          which ``qteMakeAppletActive`` and/or ``qteMakeWidgetActive``
          were called last. If these applets do not exist anymore, then
          the next possible widget and or applet will be chosen.
  
          To trigger the focus manger *do not call this method
          directly*, but use ``qteUpdate`` instead. This ensures that
          the focus manager only runs *after* the Qt event loop was able
          to show/hide all the widgets and update internal status variables
          like the Qt native ``isVisible``.
  
          This method also performs several sanity checks to ensure that
          all visible applets are part of a splitter while all invisible
          applets are not. Violations of this rule are reported and
          should be debugged, as otherwise floating applets are a
          possibility.
  
          The focus policy:
          ------------------
  
          Facts:
  
            * There are windows, applets in windows, and widgets in applets.
            * The currently active applet is QtmacsMain._qteActiveApplet.
            * The currently active widget inside that applet is
              QtmacsApplet._qteActiveWidget.
            * No one except the focus manager calls the Qt native ``setFocus``
              or ``activateWindow`` methods.
            * To queue an applet/widget for activation call
              ``qteMake{Applet,Widget}Active``. This will update the
              aforementioned variables ``_qteActiveApplet`` and
              ``_qteActiveWidget`` attributes in ``QtmacsMain`` and
              ``QtmacsApplet``, respectively.
            * The focus manager will inspect these variables and make the
              specified applet and widget active, if they still exists. If they
              do not exists, it will automatically pick a substitute.
  
          The tasks of the focus manager are, in this order:
  
            * Ensure Qt and Qtmacs agree on what is currently visible and
              go into damage control if this does not check out.
            * Activate the top level window containing ``_qteActiveApplet``.
            * Focus the active widget ``_qteActiveWidget`` inside the applet.
  
          |Args|
  
          * **None**
  
          |Returns|
  
          * **None**
  
          |Raises|
  
          * **None**
          """
          # Process all but user input events.
          flag = QtCore.QEventLoop.ExcludeUserInputEvents
          qApp = QtGui.QApplication.instance()
          qApp.processEvents(flag)
  
          # Ensure _qteActiveApplet is not a dangling pointer.
          if self._qteActiveApplet is not None:
              if sip.isdeleted(self._qteActiveApplet):
                  self._qteActiveApplet = None
  
          # Perform sanity checks on all applets.
          if len(self._qteAppletList) > 0:
              # Compile a list of visible and invisible applets (include
              # the mini applet).
              isVis = [_ for _ in self._qteAppletList if _.qteIsVisible()]
              isNotVis = [_ for _ in self._qteAppletList if not _.qteIsVisible()]
  
              # Ensure that the parent of every visible applet is a
              # QtmacsSplitter instance.
              for app in isVis:
                  signatureParent = app.parent()._qteAdmin.widgetSignature
                  if signatureParent != '__QtmacsLayoutSplitter__':
                      msg = 'Applet <b>{}</b> is visible but not in splitter.'
                      msg = msg.format(app.qteAppletID())
                      self.qteLogger.error(msg, stack_info=True)
  
              # Ensure all invisible applets have no parent.
              for app in isNotVis:
                  if app.parent() is not None:
                      msg = 'Applet <b>{}</b> is invisible yet has a parent.'
                      msg = msg.format(app.qteAppletID())
                      self.qteLogger.error(msg, stack_info=True)
  
              # Ensure that Qt and Qtmacs agree on whether or not an
              # applet is visible.
              isFaulty = False
              for app in (_ for _ in self._qteAppletList
                          if(_.isVisible() != _.qteIsVisible())):
                  isFaulty = True
                  msg = 'Inconsistent visibility for applet <b>{}</b>.'
                  msg = msg.format(app.qteAppletID())
                  msg += ' Qt: {}, Qtmacs: {}'
                  msg = msg.format(app.isVisible(), app.qteIsVisible())
                  self.qteLogger.error(msg, stack_info=True)
  
              # If one or more visibility inconsistencies occurred then
              # go into damage control and reset the layout as best as
              # possible.
              if isFaulty:
                  msg = 'Resetting applet layout due to visibility'
                  msg += ' inconsistencies.'
                  self.qteLogger.critical(msg)
  
                  # Close all but the first window.
                  if len(self._qteWindowList) > 1:
                      for window in self._qteWindowList[1:]:
                          window.close()
  
                  # Hide all applets except the mini applet. Note that
                  # the hide() method will reparent the widget to None
                  # which implies that they are also removed from any
                  # they might be in.
                  for app in (_ for _ in self._qteAppletList
                              if _ is not self._qteMiniApplet):
                      app.hide(True)
  
                  # Manually insert the first applet into the splitter
                  # and make it visible.
                  if len(self._qteAppletList) > 0:
                      app = self._qteAppletList[0]
  
          # ------------------------------------------------------------
          # If the _qteActiveApplet pointer is void try to assign it
          # another applet, even if it is just the mini applet. If
          # nothing is available, then return.
          # ------------------------------------------------------------
          if self._qteActiveApplet is None:
              if len(self._qteAppletList) > 0:
                  self._qteActiveApplet = self.qteNextApplet(
                      numSkip=0, skipMiniApplet=False)
              else:
                  win = self._qteWindowList[0]
                  self._qteActiveApplet = None
  
          if self._qteActiveApplet is None:
              return
  
          # ------------------------------------------------------------
          # Activate the Qt window that harbours the applet and is only
          # relevant if multiple windows are open. The activation is
          # necessary because giving the focus to a any widget (an
          # applet in this case) does not automatically active the
          # window it is in (see Qt documentation for more details).
          # This is the only place in Qtmacs where the Qt libraray is
          # actually instructed to activate a window.
          # ------------------------------------------------------------
          try:
              self._qteActiveApplet.activateWindow()
          except Exception as err:
              msg = 'Qt had a serious problem activating a window'
              msg += ' --> try to reproduce.'
              print(msg)
              print('Raised error:', err)
              print('Current applet', self._qteActiveApplet)
              self.qteLogger.exception('Tried to focus a non-existing applet.',
                                       exc_info=True, stack_info=True)
  
          # Shorthand.
          app = self._qteActiveApplet
          self.qteMakeAppletActive(app)
  
          # ------------------------------------------------------------
          # Activate the next focusable widget in the applet. Note that
          # the qteMakeWidgetActive method
          #   * can cope with nextWidget being None,
          #   * does not actually set the focus of anything but only
          #     asks Qtmacs to do it. The actual focussing is done
          #     a few lines further down.
          # ------------------------------------------------------------
          wid = app.qteNextWidget(numSkip=0)
          app.qteMakeWidgetActive(wid)
  
          # ------------------------------------------------------------
          # Actually focus the active widget in the active applet. This
          # is the only place in Qtmacs where the Qt library is actually
          # instructed to focus a widget.
          # ------------------------------------------------------------
          try:
              if app._qteActiveWidget is None:
                  app.setFocus(QtCore.Qt.OtherFocusReason)
              else:
                  app._qteActiveWidget.setFocus(QtCore.Qt.OtherFocusReason)
          except Exception as err:
              print('Serious problem activating the applet --> '
                    'try to reproduce.')
              print('Raised error:', err)
              print('Current applet object', app)
              print('Next widget: ', nextWidget)
              print('Current applet ID', app.qteAppletID())
              print('Active widget inside this applet', app._qteActiveWidget)
              self.qteLogger.exception('Tried to focus a non-existing applet.',
                                       exc_info=True, stack_info=True)