Package com.iizix.gyro

Interface IFocusEngine

All Known Subinterfaces:
IVirtualSpaceFocusEngine
public interface IFocusEngine
Interface implemented by the focus engine.

Focus processing is done in the following order:

  1. Focus is changed in the focus engine without notification, i.e. the call to getCurrentFocus() will reflect the new focus component,
     
  2. If the receiving focus component is non-null: focus veto processing using the focus listeners registered in the IFocusEngine using the IFocusVetoListener interface. If the FocusVetoException is thrown, the original focus is restored in the focus engine without notification.
     
  3. Focus lost sent to the component losing focus using method IFocusComp.onFocusLost(IFocusComp, IGProp, boolean) in the event FocusEvent.
     
  4. Focus lost is notified in a bubbling event PropFocusEvent to the component losing focus and its parents. with PropFocusEvent.isFocusLost() true.
     
  5. Focus lost is notified in a sinking event PropCnrFocusEvent to the component losing focus and its descendants with PropCnrFocusEvent.isFocusLost() true.
     
  6. Focus change sent to the focus listeners registered in the IFocusEngine using IFocusListener.onFocusChanged(FocusEvent).
     
  7. Focus gained sent to the component gaining focus using method IFocusComp.onFocusGained(IFocusComp, IGProp, boolean) in the event FocusEvent.
     
  8. Focus gained is notified in a bubbling event PropFocusEvent to the component gaining focus and its parents. with PropFocusEvent.isFocusGained() true.
     
  9. Focus gained is notified in a sinking event PropCnrFocusEvent to the component gaining focus and its descendants with PropCnrFocusEvent.isFocusGained() true.
     
Author:
Christopher Mindus

  • Method Details

    • hasCommonFocus

      boolean hasCommonFocus()
      Checks if this focus engine is common to all parallel client sessions. E.g. the VirtualSpace engine returns true, and the Panel engine returns false.
      Returns:
      true if the focus engine is common to all parallel client session, false otherwise.

    • requestFocus

      String requestFocus(IFocusComp comp, IGProp<?> trigger, boolean isRemoteInduced, IFocusVetoListener callback)
      Requests focus to this component. This call is redirected to the focus engine for the component type. The engine may veto the focus change, because it currently cannot change focus, or the request is not or cannot be virtualized.

      This method is less precise than requestFocusEx(IFocusComp, IGProp, boolean, IFocusVetoListener), but avoid try-catching.

      Parameters:
      comp - The component requesting focus.
      trigger - The trigger property, null for none.
      isRemoteInduced - Flag for remote induced focus.
      callback - Optional callback that may throw a veto exception, null for none. This callback is intended to perform focus changes in the tree, typically for UI containers.
      Returns:
      null for success, otherwise an error message indicating why focus was not able to be changed.
      Throws:
      NullPointerException - If comp is null.

    • requestFocusEx

      boolean requestFocusEx(IFocusComp comp, IGProp<?> trigger, boolean isRemoteInduced, IFocusVetoListener callback) throws FocusException
      Requests focus to this component. This call is redirected to the focus engine for the component type. The engine may veto the focus change, because it currently cannot change focus, or the request is not or cannot be virtualized.
      Parameters:
      comp - The component requesting focus.
      trigger - The trigger property, null for none.
      isRemoteInduced - Flag for remote induced focus.
      callback - Optional callback that may throw a veto exception, null for none. This callback is intended to perform focus changes in the tree, typically for UI containers.
      Returns:
      true if focus was changed, false otherwise.
      Throws:
      FocusException - If focus could not be changed.
      NullPointerException - If comp is null.

    • getCurrentFocus

      IFocusComp getCurrentFocus()
      Gets the component in focus.
      Returns:
      The component or property in current focus, null for none.

    • addFocusListener

      boolean addFocusListener(IFocusListener listener)
      Adds a focus listener to the engine.
      Parameters:
      listener - The focus listener.
      Returns:
      true if the listener is added, false if already added as a listener previously.

    • addFocusVetoListener

      boolean addFocusVetoListener(IFocusVetoListener listener)
      Adds a veto focus listener to the engine.
      Parameters:
      listener - The veto focus listener.
      Returns:
      true if the listener is added, false if already added as a listener previously.

    • removeFocusListener

      boolean removeFocusListener(IFocusListener listener)
      Removes a focus listener from the engine.
      Parameters:
      listener - The focus listener.
      Returns:
      true if the listener is removed, false if not present.

    • removeFocusVetoListener

      boolean removeFocusVetoListener(IFocusVetoListener listener)
      Removes a veto focus listener from the engine.
      Parameters:
      listener - The veto focus listener.
      Returns:
      true if the listener is removed, false if not present.

    • getFocusListeners

      IFocusListener[] getFocusListeners()
      Gets the current focus listeners.
      Returns:
      An array of the focus listeners.

    • getFocusVetoListeners

      IFocusVetoListener[] getFocusVetoListeners()
      Gets the current veto focus listeners.
      Returns:
      An array of the veto focus listeners.