org.jdesktop.swingx.prompt.PromptSupport Maven / Gradle / Ivy
Show all versions of swingx-all Show documentation
package org.jdesktop.swingx.prompt;
import java.awt.Color;
import java.awt.Font;
import javax.swing.text.JTextComponent;
import org.jdesktop.swingx.JXFormattedTextField;
import org.jdesktop.swingx.JXTextArea;
import org.jdesktop.swingx.JXTextField;
import org.jdesktop.swingx.painter.Painter;
import org.jdesktop.swingx.painter.Painters;
import org.jdesktop.swingx.plaf.PromptTextUI;
import org.jdesktop.swingx.plaf.TextUIWrapper;
/**
*
* Sets prompt text, foreground, background and {@link FocusBehavior} properties
* on a JTextComponent by calling
* {@link JTextComponent#putClientProperty(Object, Object)}. These properties
* are used by {@link PromptTextUI} instances to render the prompt of a text
* component.
*
*
*
* This class is used by {@link JXTextField}, {@link JXFormattedTextField} and
* {@link JXTextArea} to get and set prompt properties. {@link PromptTextUI}
* retrieves these properties using PromptSupport.
*
*
* @see JXTextField
* @see JXFormattedTextField
* @see JXTextArea
* @see PromptTextUI
*
* @author Peter Weishapl
* @author Karl Schaefer
*/
public final class PromptSupport {
/**
* The prompt text property.
*/
public static final String PROMPT = "promptText";
/**
* The color of the prompt text property.
*/
public static final String FOREGROUND = "promptForeground";
/**
* The prompt background property.
*/
public static final String BACKGROUND = "promptBackground";
/**
* The prompt background property.
*/
public static final String BACKGROUND_PAINTER = "promptBackgroundPainter";
/**
* The focus behavior property.
*/
public static final String FOCUS_BEHAVIOR = "focusBehavior";
/**
* The font style property, if different from the components font.
*/
public static final String FONT_STYLE = "promptFontStyle";
/**
*
* Determines how the {@link JTextComponent} is rendered when focused and no
* text is present.
*
*/
public static enum FocusBehavior {
/**
* Keep the prompt text visible.
*/
SHOW_PROMPT,
/**
* Highlight the prompt text as it would be selected.
*/
HIGHLIGHT_PROMPT,
/**
* Hide the prompt text.
*/
HIDE_PROMPT
};
private PromptSupport() {
//prevent instantiation
}
/**
*
* Convenience method to set the promptText and
* promptTextColor on a {@link JTextComponent}.
*
*
* If stayOnUIChange is true, The prompt support will stay
* installed, even when the text components UI changes. See
* {@link #install(JTextComponent, boolean)}.
*
*
* @param promptText
* @param promptForeground
* @param promptBackground
* @param textComponent
*/
public static void init(String promptText, Color promptForeground, Color promptBackground,
final JTextComponent textComponent) {
if (promptText != null && promptText.length() > 0) {
setPrompt(promptText, textComponent);
}
if (promptForeground != null) {
setForeground(promptForeground, textComponent);
}
if (promptBackground != null) {
setBackground(promptBackground, textComponent);
}
}
/**
* Get the {@link FocusBehavior} of textComponent.
*
* @param textComponent
* @return the {@link FocusBehavior} or {@link FocusBehavior#HIDE_PROMPT} if
* none is set
*/
public static FocusBehavior getFocusBehavior(JTextComponent textComponent) {
FocusBehavior fb = (FocusBehavior) textComponent.getClientProperty(FOCUS_BEHAVIOR);
if (fb == null) {
fb = FocusBehavior.HIDE_PROMPT;
}
return fb;
}
/**
* Sets the {@link FocusBehavior} on textComponent and
* repaints the component to reflect the changes, if it is the focus owner.
*
* @param focusBehavior
* @param textComponent
*/
public static void setFocusBehavior(FocusBehavior focusBehavior, JTextComponent textComponent) {
textComponent.putClientProperty(FOCUS_BEHAVIOR, focusBehavior);
if (textComponent.isFocusOwner()) {
textComponent.repaint();
}
}
/**
* Get the prompt text of textComponent.
*
* @param textComponent
* @return the prompt text
*/
public static String getPrompt(JTextComponent textComponent) {
return (String) textComponent.getClientProperty(PROMPT);
}
/**
*
* Sets the prompt text on textComponent. Also sets the
* tooltip text to the prompt text if textComponent has no
* tooltip text or the current tooltip text is the same as the current
* prompt text.
*
*
* Calls {@link #install(JTextComponent)} to ensure that the
* textComponents UI is wrapped by the appropriate
* {@link PromptTextUI}.
*
*
* @param promptText
* @param textComponent
*/
public static void setPrompt(String promptText, JTextComponent textComponent) {
TextUIWrapper.getDefaultWrapper().install(textComponent, true);
// display prompt as tooltip by default
if (textComponent.getToolTipText() == null || textComponent.getToolTipText().equals(getPrompt(textComponent))) {
textComponent.setToolTipText(promptText);
}
textComponent.putClientProperty(PROMPT, promptText);
textComponent.repaint();
}
/**
* Get the foreground color of the prompt text. If no color has been set,
* the textComponents disabled text color will be returned.
*
* @param textComponent
* @return the color of the prompt text or
* {@link JTextComponent#getDisabledTextColor()} if none is set
*/
public static Color getForeground(JTextComponent textComponent) {
if (textComponent.getClientProperty(FOREGROUND) == null) {
return textComponent.getDisabledTextColor();
}
return (Color) textComponent.getClientProperty(FOREGROUND);
}
/**
* Sets the foreground color of the prompt on textComponent
* and repaints the component to reflect the changes. This color will be
* used when no text is present.
*
* @param promptTextColor
* @param textComponent
*/
public static void setForeground(Color promptTextColor, JTextComponent textComponent) {
textComponent.putClientProperty(FOREGROUND, promptTextColor);
textComponent.repaint();
}
/**
* Get the background color of the textComponent, when no
* text is present. If no color has been set, the textComponents
* background color color will be returned.
*
* @param textComponent
* @return the the background color of the text component, when no text is
* present
*/
public static Color getBackground(JTextComponent textComponent) {
if (textComponent.getClientProperty(BACKGROUND) == null) {
return textComponent.getBackground();
}
return (Color) textComponent.getClientProperty(BACKGROUND);
}
/**
*
* Sets the prompts background color on textComponent and
* repaints the component to reflect the changes. This background color will
* only be used when no text is present.
*
*
* Calls {@link #install(JTextComponent)} to ensure that the
* textComponents UI is wrapped by the appropriate
* {@link PromptTextUI}.
*
*
* @param background
* @param textComponent
*/
public static void setBackground(Color background, JTextComponent textComponent) {
TextUIWrapper.getDefaultWrapper().install(textComponent, true);
textComponent.putClientProperty(BACKGROUND, background);
textComponent.repaint();
}
/**
* Get the background painter of the textComponent, when no
* text is present. If no painter has been set, then {@code null} will be returned.
*
* @param textComponent
* @return the background painter of the text component
*/
@SuppressWarnings("unchecked")
public static Painter getBackgroundPainter(T textComponent) {
Painter painter = (Painter) textComponent.getClientProperty(BACKGROUND_PAINTER);
if (painter == null) {
painter = Painters.EMPTY_PAINTER;
}
return painter;
}
/**
*
* Sets the prompts background painter on textComponent and
* repaints the component to reflect the changes. This background painter will
* only be used when no text is present.
*
*
* Calls {@link #install(JTextComponent)} to ensure that the
* textComponents UI is wrapped by the appropriate
* {@link PromptTextUI}.
*
*
* @param background
* @param textComponent
*/
public static void setBackgroundPainter(Painter background, T textComponent) {
TextUIWrapper.getDefaultWrapper().install(textComponent, true);
textComponent.putClientProperty(BACKGROUND_PAINTER, background);
textComponent.repaint();
}
/**
*
* Set the style of the prompt font, if different from the
* textComponents font.
*
*
* Allowed values are {@link Font#PLAIN}, {@link Font#ITALIC},
* {@link Font#BOLD}, a combination of {@link Font#BOLD} and
* {@link Font#ITALIC} or null if the prompt font should be
* the same as the textComponents font.
*
*
* @param fontStyle
* @param textComponent
*/
public static void setFontStyle(Integer fontStyle, JTextComponent textComponent) {
textComponent.putClientProperty(FONT_STYLE, fontStyle);
textComponent.revalidate();
textComponent.repaint();
}
/**
* Returns the font style of the prompt text, or null if the
* prompt's font style should not differ from the textComponents
* font.
*
* @param textComponent
* @return font style of the prompt text
*/
public static Integer getFontStyle(JTextComponent textComponent) {
return (Integer) textComponent.getClientProperty(FONT_STYLE);
}
}