Interface UIInputReceiver

  • All Known Subinterfaces:
    UISWTInputReceiver
    All Known Implementing Classes:
    AbstractUIInputReceiver, AbstractUISWTInputReceiver, SimpleTextEntryWindow

    public interface UIInputReceiver
    This interface provides a mechanism to get some textual input from a user.

    There are various methods which allow you to customise the appearance of the prompt that the user receives - subclasses may provide additional methods to customise the interface too.

    Once the object has been set up, you then call prompt(UIInputReceiverListener) This will ask the user for some input based on the values previously given. UIInputReceiverListener will only trigger once the user has either given some validated input, or has indicated they don't want to give any input (like pressing a Cancel button).

    The hasSubmittedInput() and getSubmittedInput() methods can then be invoked to retrieve the input (if the user has submitted any).

    There are various methods which have a setXXX and setLocalisedXXX counterparts. The setXXX methods will attempt to translate the given string to a localised representation of it - the setLocalisedXXX method will assume that the localisation has already been done, and leave it intact.

    Note: Only for implementation by Azureus, not plugins.

    • Method Summary

      All Methods Instance Methods Abstract Methods 
      Modifier and Type Method Description
      void allowEmptyInput​(boolean empty_input)
      Indicates whether blank input can be entered.
      java.lang.String getSubmittedInput()
      Returns the string if the user submitted any data - you should check for this by calling hasSubmittedInput() first.
      boolean hasSubmittedInput()
      Returns true if the user submitted any data.
      void maintainWhitespace​(boolean keep_whitespace)
      Indicates whether to keep whitespace are kept when input is entered, or whether to strip it out.
      void prompt​(UIInputReceiverListener receiver_listener)
      This prompts the user for input and returns immediately.
      void setEnableSpecialEscapeHandling​(boolean b)
      Enables a long-press on cancel button to be treated as an escape - useful for callers that implement special escape handling such as 'escape closes this and any other similar outstanding dialogs', e.g.
      void setInputValidator​(UIInputValidator validator)
      Sets the UIInputValidator for this object.
      void setLocalisedMessage​(java.lang.String message)
      Sets the message to display for the text entry input.
      void setLocalisedMessages​(java.lang.String[] messages)
      Sets the message to display for the text entry input.
      void setLocalisedTitle​(java.lang.String title)
      Sets the title for the text entry input.
      void setMessage​(java.lang.String message)
      Sets the message to display for the text entry input.
      void setMessages​(java.lang.String[] messages)
      Sets the message to display for the text entry input.
      void setMultiLine​(boolean multiline)
      Indicates whether to allow multi-line input.
      void setPreenteredText​(java.lang.String text, boolean as_suggested)
      This sets a value to be displayed as pre-entered text for the input.
      void setTextLimit​(int limit)
      set the maximum number of characters the user can type
      void setTitle​(java.lang.String title)
      Sets the title for the text entry input.
      boolean userHitEscape()  
    • Method Detail

      • setTitle

        void setTitle​(java.lang.String title)
        Sets the title for the text entry input. For some interfaces, this means that a window will be presented, and the title of the window will be the value passed here.
      • setLocalisedTitle

        void setLocalisedTitle​(java.lang.String title)
        Sets the title for the text entry input. For some interfaces, this means that a window will be presented, and the title of the window will be the value passed here.
      • setMessage

        void setMessage​(java.lang.String message)
        Sets the message to display for the text entry input. This will normally be displayed near the position where the text will be entered - this method is usually used to present the user with an indication of what to enter.

        For multiple lines, see setMessages(java.lang.String[]).

      • setLocalisedMessage

        void setLocalisedMessage​(java.lang.String message)
        Sets the message to display for the text entry input. This will normally be displayed near the position where the text will be entered - this method is usually used to present the user with an indication of what to enter.

        For multiple lines, see setLocalisedMessages(java.lang.String[]).

      • setMessages

        void setMessages​(java.lang.String[] messages)
        Sets the message to display for the text entry input. This will normally be displayed near the position where the text will be entered - this method is usually used to present the user with an indication of what to enter.

        The value passed here will be an array of strings - each string will be usually outputted on its own line. The last value in the array will usually be the message displayed closest to the users prompt.

      • setLocalisedMessages

        void setLocalisedMessages​(java.lang.String[] messages)
        Sets the message to display for the text entry input. This will normally be displayed near the position where the text will be entered - this method is usually used to present the user with an indication of what to enter.

        The value passed here will be an array of strings - each string will be usually outputted on its own line. The last value in the array will usually be the message displayed closest to the users prompt.

      • setPreenteredText

        void setPreenteredText​(java.lang.String text,
                               boolean as_suggested)
        This sets a value to be displayed as pre-entered text for the input. This may be called if the caller wants to suggest a value for the user to use, or if the caller wants to provide a previous value (for example).

        The text may appear in the same location as the text should be entered (allowing it to be directly overwritten or submitted immediately) - but some interfaces may not support this.

        A flag should be passed indicating whether the pre-entered text is being entered as a suggestion for a value, or whether it is an old value being currently stored. Some interfaces may choose to differentiate between the two.

        Parameters:
        text - The text to pre-enter.
        as_suggested - true if the value is a suggested input value, false if it is an old value.
      • setMultiLine

        void setMultiLine​(boolean multiline)
        Indicates whether to allow multi-line input. Default behaviour is to not allow multiple lines.
      • maintainWhitespace

        void maintainWhitespace​(boolean keep_whitespace)
        Indicates whether to keep whitespace are kept when input is entered, or whether to strip it out. Default behaviour is to strip whitespace.
      • allowEmptyInput

        void allowEmptyInput​(boolean empty_input)
        Indicates whether blank input can be entered.
      • setInputValidator

        void setInputValidator​(UIInputValidator validator)
        Sets the UIInputValidator for this object. This allows an external object to validate or reject input submitted by the user.

        By default, there is no input validator associated with a UIInputReceiver, meaning all input is allowed.

        See Also:
        UIInputValidator
      • prompt

        void prompt​(UIInputReceiverListener receiver_listener)
        This prompts the user for input and returns immediately. When the user has closed the input ui, the UIInputReceiverListener will be triggered
        Parameters:
        receiver_listener -
        Since:
        4.2.0.9
      • hasSubmittedInput

        boolean hasSubmittedInput()
        Returns true if the user submitted any data.
      • getSubmittedInput

        java.lang.String getSubmittedInput()
        Returns the string if the user submitted any data - you should check for this by calling hasSubmittedInput() first.
      • setTextLimit

        void setTextLimit​(int limit)
        set the maximum number of characters the user can type
        Since:
        4.3.1.5
      • setEnableSpecialEscapeHandling

        void setEnableSpecialEscapeHandling​(boolean b)
        Enables a long-press on cancel button to be treated as an escape - useful for callers that implement special escape handling such as 'escape closes this and any other similar outstanding dialogs', e.g. when renaming a number of files this can avoid the user having to explicitly cancel each rename if they decide to abort the operation
        Parameters:
        b -
      • userHitEscape

        boolean userHitEscape()