org.gudy.azureus2.plugins.ui
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 the prompt()method. This will ask the user for some input based on the values previously given. It will only return 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 #hasSubmittedText() and #getSubmittedText() 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
 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()
          Deprecated. Use prompt(UIInputReceiverListener)
 void prompt(UIInputReceiverListener receiver_listener)
          This prompts the user for input and returns immediately.
 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.
 

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

@Deprecated
void prompt()
Deprecated. Use prompt(UIInputReceiverListener)

This prompts the user for input. This method will not return until the user has either entered valid input, or signalled they want to cancel entering any data.


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