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**

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)