Package ca.corbett.forms.fields

Class LabelField

java.lang.Object
ca.corbett.forms.fields.FormField
ca.corbett.forms.fields.LabelField
public final class LabelField extends FormField
Represents a form field that just presents a static label without any user interaction. This can either be presented as a label:text pair, like a non-editable form field, or as a single label that spans the width of the form, like a section header. Convenience methods are exposed here so you can control the font and colour of the label text. (You could also do this by invoking getFieldComponent() from the FormField parent class and casting it to a JLabel, but the convenience methods here are easier). To reduce confusion, the terminology is as follows: (fieldLabel):(labelText), where (fieldLabel) is optional (if not set, the colon separator will also be hidden).

You can make a multiline label by wrapping the label text in html tags: 

labelField.setText("<html>Hello<br>second line<br>another line</html>");

Hyperlinks


Hyperlinked labels are supported by using the setHyperlink() method and providing some Action to be invoked when the link is clicked. This will change the color of the label to blue and change the mouse pointer when the cursor is over the label, to indicate that the label is clickable. Note that with LabelField, this is all-or-nothing: the entire label will be converted to a single hyperlink. If you only want to change part of the label text to a hyperlink, or if you wish to have multiple hyperlinks in a single label, you should use the HtmlLabelField class instead.
Since:
2019-11-26
Author:
scorbo2

  • Constructor Details

    • LabelField

      public LabelField(String labelText)
      Creates a form-width label in the format "labelText".
      Parameters:
      labelText - The text of the label.

    • LabelField

      public LabelField(String fieldLabelText, String labelText)
      Creates a label field in the format "fieldLabel:labelText". If fieldLabel is null or blank, only "labelText" will be displayed.
      Parameters:
      fieldLabelText - The optional string to show as a prefix. Can be null or blank to omit.
      labelText - The text of the actual label.

  • Method Details

    • hasValidationLabel

      public boolean hasValidationLabel()
      Overridden here as we generally don't want to show a validation label on a label. Will return true only if one or more FieldValidators have been explicitly assigned. Yes! You can assign a FieldValidator to a LabelField if you really want to, and it will perform validation if so. This generally makes no sense, as LabelFields do not allow user input, and so validation is disabled by default.
      Overrides:
      hasValidationLabel in class FormField

    • createBoldHeaderLabel

      public static LabelField createBoldHeaderLabel(String text)
      A static convenience factory method to create a bold header label with sensible defaults for a section header label. The default values are 16 point bold text with a slightly larger top margin and normal bottom margin.

      You can control the extra top and bottom margin for generated header labels by invoking LabelField.setHeaderLabelExtraMargins() before invoking this method.

      Parameters:
      text - The label text
      Returns:
      A LabelField suitable for use as a header.

    • createBoldHeaderLabel

      public static LabelField createBoldHeaderLabel(String text, int fontSize)
      A static convenience factory method to create a bold header label with the given font size and with default margins.

      You can control the extra top and bottom margin for generated header labels by invoking LabelField.setHeaderLabelExtraMargins() before invoking this method.

      Parameters:
      text - The label text
      fontSize - The point size for the label text
      Returns:
      A LabelField suitable for use as a header.

    • createBoldHeaderLabel

      public static LabelField createBoldHeaderLabel(String text, int fontSize, int extraTopMargin, int extraBottomMargin)
      A static convenience factory method to create a bold header label with the given font size and margins.
      Parameters:
      text - The label text
      fontSize - The point size for the label text
      extraTopMargin - An extra margin to apply above the LabelField
      extraBottomMargin - An extra margin to apply below the LabelField
      Returns:
      A LabelField suitable for use as a header.

    • createPlainHeaderLabel

      public static LabelField createPlainHeaderLabel(String text)
      A static convenience factory method to create a "plain" header label with sensible defaults for a form label. The default values are 12 point plain text with top and bottom margin values read from our current margin properties.

      You can control the extra top and bottom margin for generated header labels by invoking LabelField.setHeaderLabelExtraMargins() before invoking this method.

      Parameters:
      text - The label text
      Returns:
      A LabelField suitable for use as a regular header label.

    • createPlainHeaderLabel

      public static LabelField createPlainHeaderLabel(String text, int extraTopMargin, int extraBottomMargin)
      A static convenience factory method to create a "plain" header label with default font and with the given extra top and bottom margins.

    • createPlainHeaderLabel

      public static LabelField createPlainHeaderLabel(String text, int fontSize)
      A static convenience factory method to create a "plain" header label with the given font size and with top and bottom margin values read from our current margin properties.

      You can control the extra top and bottom margin for generated header labels by invoking LabelField.setHeaderLabelExtraMargins() before invoking this method.

      Parameters:
      text - The label text
      Returns:
      A LabelField suitable for use as a regular header label.

    • createPlainHeaderLabel

      public static LabelField createPlainHeaderLabel(String text, int fontSize, int extraTopMargin, int extraBottomMargin)
      A static convenience factory method to create a "plain" header label with the given font size and extra margins for top and bottom.

    • setHeaderLabelExtraMargins

      public static void setHeaderLabelExtraMargins(int normalTop, int normalBottom, int headerTop, int headerBottom)
      Sets the extra top and bottom margin values that we use in this class when create*HeaderLabel convenience methods are invoked.
      Parameters:
      normalTop - An extra pixel margin to apply above non-bolded header labels.
      normalBottom - An extra pixel margin to apply below non-bolded header labels.
      headerTop - An extra pixel margin to apply above bold header labels.
      headerBottom - An extra pixel margin to apply below bold header labels.

    • getExtraTopMarginNormal

      public static int getExtraTopMarginNormal()

    • getExtraBottomMarginNormal

      public static int getExtraBottomMarginNormal()

    • getExtraTopMarginHeader

      public static int getExtraTopMarginHeader()

    • getExtraBottomMarginHeader

      public static int getExtraBottomMarginHeader()

    • getDefaultHeaderFont

      public static Font getDefaultHeaderFont()

    • getDefaultLabelFont

      public static Font getDefaultLabelFont()

    • createHeaderLabel

      public static LabelField createHeaderLabel(String text, Font font, int topMargin, int bottomMargin)
      A static convenience factory method to create a header label with the specified font and margin properties.
      Parameters:
      text - The text to display.
      font - The font.
      topMargin - The top margin (default is 4).
      bottomMargin - The bottom margin (default is 4).
      Returns:
      A header label with the specified properties.

    • setLabelHyperlink

      public static void setLabelHyperlink(JLabel label, Action action)
      Static convenience method to restyle the given JLabel to look like a hyperlink - this involves changing the font color, adding an underline effect, changing the mouse cursor when hovering over the label, and executing the given Action when the label is clicked.

    • isLabelHyperlinked

      public static boolean isLabelHyperlinked(JLabel label)
      Static convenience method to report if the given JLabel has been styled by the setLabelHyperlink method to look like a hyperlink.

    • removeLabelHyperlink

      public static void removeLabelHyperlink(JLabel label)
      Can be used to "un-style" an image that was styled by the setLabelHyperlink method to look like a JLabel. This will also remove the mouse listener so that its hyperlink action will no longer trigger when the label is clicked.

    • isHeaderLabel

      public boolean isHeaderLabel()
      Reports whether this is a "header" label. That means the fieldLabel text is blank or empty, so instead of a fieldLabel:labeltext pairing, we just have a formwidth-spanning labeltext instead.
      Returns:
      true if this is a single label instead of this:that style.

    • isHyperlinked

      public boolean isHyperlinked()
      Reports whether this label has been hyperlinked (see setHyperlink).
      Returns:
      true if this label contains a hyperlink.

    • setHyperlink

      public LabelField setHyperlink(Action action)
      Converts the field label (if present) or the header label (if isHeaderLabel()) into a hyperlink, by adding a custom mouse cursor and mouse listener with the given ActionListener attached to the single click event. The label font is also modified with color and underline and custom mouse cursor as hints that it is now clickable.

      But I want the field label to be a hyperlink, not the main label! - this can be achieved via the static setLabelHyperlink method: LabelField.setLabelHyperlink(myLabelField.getFieldLabel(), myAction); ... but note that this only applies if the fieldLabel is visible (that is, if isHeaderLabel() is false).

      Parameters:
      action - The Action to fire when the label is clicked.

    • clearHyperlink

      public void clearHyperlink()
      Removes any previously set hyperlink, if any. This will return the label to DEFAULT_FONT and default label text color.

    • getText

      public String getText()
      Returns the current label text.
      Returns:
      The text of the label.

    • setText

      public LabelField setText(String text)
      Sets the label text.
      Parameters:
      text - The new label text.

    • setFont

      public LabelField setFont(Font font)
      Sets the font to use for the label text. This is shorthand for ((JLabel)getFieldComponent()).setFont()
      Parameters:
      font - The new Font to use.

    • getFont

      public Font getFont()

    • setColor

      public LabelField setColor(Color c)
      Sets the colour for the label text. This is shorthand for ((JLabel)getFieldComponent()).setForeground(); Be careful setting specific colors, as it may not play well with different Look and Feels! Consider using LookAndFeelManager.getLafColor() to pick a color that is appropriate for the current Look and Feel. For example, LookAndFeelManager.getLafColor("Component.linkColor", Color.BLUE); will return the standard link color for the current LaF, or blue if no specific color is defined for this LaF.
      Parameters:
      c - The new text colour.

    • getColor

      public Color getColor()