Barcode-Lib4J requires Java 11+
Package de.vwsoft.barcodelib4j.oned

Java Class «Barcode»

java.lang.Object
de.vwsoft.barcodelib4j.oned.Barcode
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
ImplCodabar, ImplCode11, ImplCode128, ImplCode39, ImplCode93, ImplITF, UPCEANFamily
public abstract class Barcode extends Object implements Cloneable
Factory class for all 1D barcode types that also serves as their abstract superclass.

This class creates instances of any 1D barcode type and provides all necessary methods to access and modify the created instance's properties. Rather than having to deal with specific derived classes, instances can be created using one of the two available static newInstance methods. Example: 

    Barcode bc = Barcode.newInstance(BarcodeType.CODE128);
    bc.set...
    bc.get...
    bc.supports...
    bc.draw...
Note: Boolean methods of the pattern "supportsXYZ" indicate whether the barcode type (not just the individual instance) supports a particular property. These properties can also be queried using identically named methods in BarcodeType. Note also that calling setter methods for unsupported properties has no effect and does not throw an exception.

  • Method Summary

    Modifier and Type
    Method
    Description
    Barcode
    clone()
    Returns a copy of this object.
    void
    draw(Graphics2D g2d, double x, double y, double w, double h)
    Draws the barcode symbol.
    void
    draw(Graphics2D g2d, double x, double y, double w, double h, double barWidthCorrection)
    Draws the barcode symbol.
    void
    draw(Graphics2D g2d, double x, double y, double w, double h, double dotSize, double moduleSize, double barWidthCorrection)
    Draws the barcode symbol.
    String
    getAddOn()
    Returns the Add-On number assigned to this barcode object or null if no Add-On number is assigned.
    String
    getContent()
    Returns the validated raw content as encoded in the barcode.
    Font
    getFont()
    Returns the font to be used for drawing the human readable text in the barcode.
    float
    getRatio()
    Returns the width ratio between wide and narrow bars in two-width barcode types.
    String
    getText()
    Returns the human readable representation of the content encoded in the barcode.
    double
    getTextOffset()
    Returns the vertical offset for the human readable text relative to the barcode symbol.
    boolean
    isFontSizeAdjusted()
    Returns whether the font size is automatically adjusted based on the size of the barcode symbol.
    boolean
    isOptionalChecksumVisible()
    Returns whether the optional checksum, if encoded in the barcode, is visible within the human readable text.
    boolean
    isTextOnTop()
    Returns whether the human readable text is placed above the barcode symbol.
    boolean
    isTextVisible()
    Returns whether the human readable representation of the content encoded in the barcode is visible or whether only the barcode symbol is drawn.
    static Barcode
    newInstance(BarcodeType type)
    Creates a new instance of the specified barcode type.
    static Barcode
    newInstance(BarcodeType type, String content, boolean autoComplete, boolean appendOptionalChecksum)
    Creates a new instance of the specified barcode type.
    void
    setAddOn(String addOnNumber)
    Sets the Add-On number for this barcode object.
    abstract void
    setContent(String content, boolean autoComplete, boolean appendOptionalChecksum)
    Sets the content to be encoded in the barcode, along with parameters that determine how the content is to be handled.
    void
    setCustomText(String text)
    Sets a custom text for the barcode to replace the automatically generated human readable text.
    void
    setFont(Font font)
    Sets the font to be used for drawing the human readable text in the barcode.
    void
    setFontSizeAdjusted(boolean b)
    Sets whether the font size is to be automatically adjusted based on the size of the barcode symbol.
    void
    setOptionalChecksumVisible(boolean visible)
    Sets whether the optional checksum, if encoded in the barcode, is to be visible within the human readable text.
    void
    setRatio(float ratio)
    Sets the width ratio between wide and narrow bars in two-width barcode types.
    void
    setTextOffset(double offset)
    Sets the vertical offset for the human readable text relative to the barcode symbol.
    void
    setTextOnTop(boolean onTop)
    Sets whether the human readable text is to be placed above the barcode symbol.
    void
    setTextVisible(boolean visible)
    Sets whether the human readable representation of the content encoded in the barcode is visible or whether only the barcode symbol is drawn.
    boolean
    supportsAddOn()
    Returns whether the given barcode type supports the addition of supplementary barcode symbols.
    boolean
    supportsAutoCompletion()
    Returns whether the given barcode type supports auto-completion.
    boolean
    supportsCustomText()
    Returns whether the given barcode type supports customization of the automatically generated human readable text.
    boolean
    supportsOptionalChecksum()
    Returns whether the given barcode type supports an optional checksum.
    boolean
    supportsRatio()
    Returns whether the given barcode type supports setting the width ratio between wide and narrow bars in the barcode symbol.
    boolean
    supportsTextOnTop()
    Returns whether the given barcode type supports placing the human readable text above the barcode symbol.

    Methods inherited from class java.lang.Object

    equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • newInstance

      public static Barcode newInstance(BarcodeType type)
      Creates a new instance of the specified barcode type.
      Parameters:
      type - the type of barcode to instantiate
      Returns:
      a new instance of an implementation of the Barcode class

    • newInstance

      public static Barcode newInstance(BarcodeType type, String content, boolean autoComplete, boolean appendOptionalChecksum) throws BarcodeException
      Creates a new instance of the specified barcode type.

      Then sets its content using the setContent method, along with parameters that determine how the content is handled.

      Parameters:
      type - the type of barcode to instantiate
      content - the content to be encoded in the barcode
      autoComplete - If true, the content will be automatically completed according to certain criteria (e.g., padding or formatting rules)
      appendOptionalChecksum - If true, an optional checksum will be calculated and appended to the barcode if the barcode type supports it
      Returns:
      a new instance of an implementation of the Barcode class
      Throws:
      BarcodeException - if the provided content cannot be encoded by the given barcode type

    • setContent

      public abstract void setContent(String content, boolean autoComplete, boolean appendOptionalChecksum) throws BarcodeException
      Sets the content to be encoded in the barcode, along with parameters that determine how the content is to be handled.

      This is an abstract method. Please refer to the specific implementation of this method in the respective barcode type class for detailed information:

      Parameters:
      content - the content to be encoded in the barcode
      autoComplete - controls whether the content is automatically completed according to certain criteria. For example, for certain barcode types, such as those that require padding or formatting rules, enabling autoComplete will ensure that these requirements are met. Some barcode types are forced to calculate a missing checksum. The effect of autoComplete varies between barcode types.
      appendOptionalChecksum - applies to barcode types that may or may not contain a checksum. If enabled, the checksum will be calculated and appended to the barcode. However, this parameter has no effect on barcode types for which a checksum is either mandatory or not provided by their specification.
      Throws:
      BarcodeException - if a barcode object is assigned an invalid content that cannot be encoded by the given barcode type

    • getContent

      public String getContent()
      Returns the validated raw content as encoded in the barcode.

      Note that depending on the given barcode type (e.g., Code 128 and EAN-128) the returned string may contain non-printable characters, such as ASCII values from 0 to 31 and others. For human readable text, consider using the getText() method instead.

      Returns:
      the validated raw content as encoded in the barcode

    • supportsCustomText

      public boolean supportsCustomText()
      Returns whether the given barcode type supports customization of the automatically generated human readable text.
      Returns:
      whether the given barcode type supports customization of the automatically generated human readable text
      See Also:

    • setCustomText

      public void setCustomText(String text)
      Sets a custom text for the barcode to replace the automatically generated human readable text.

      This must be supported by the given barcode type. See: supportsCustomText()

      Parameters:
      text - the custom text to set for the barcode
      Throws:
      NullPointerException - if the custom text is null
      IllegalArgumentException - if the custom text is empty

    • getText

      public String getText()
      Returns the human readable representation of the content encoded in the barcode.
      Returns:
      the human readable representation of the content encoded in the barcode

    • supportsAddOn

      public boolean supportsAddOn()
      Returns whether the given barcode type supports the addition of supplementary barcode symbols.

      This feature is specific to barcode types in the UPC family, such as UPC-A, UPC-E, EAN-13, EAN-8, ISBN-13 and ISMN.

      Returns:
      whether the given barcode type supports the addition of supplementary barcode symbols
      See Also:

    • setAddOn

      public void setAddOn(String addOnNumber) throws BarcodeException
      Sets the Add-On number for this barcode object.

      This must be supported by the given barcode type. See: supportsAddOn()

      Parameters:
      addOnNumber - a number consisting of either 2 or 5 digits or null (default)
      Throws:
      BarcodeException - if the provided value does not match the expected format

    • getAddOn

      public String getAddOn()
      Returns the Add-On number assigned to this barcode object or null if no Add-On number is assigned.
      Returns:
      the Add-On number assigned to this barcode object or null if no Add-On number is assigned

    • setTextVisible

      public void setTextVisible(boolean visible)
      Sets whether the human readable representation of the content encoded in the barcode is visible or whether only the barcode symbol is drawn.
      Parameters:
      visible - true if the human readable text should be visible, false otherwise

    • isTextVisible

      public boolean isTextVisible()
      Returns whether the human readable representation of the content encoded in the barcode is visible or whether only the barcode symbol is drawn.
      Returns:
      whether the human readable representation of the content encoded in the barcode is visible or whether only the barcode symbol is drawn

    • supportsTextOnTop

      public boolean supportsTextOnTop()
      Returns whether the given barcode type supports placing the human readable text above the barcode symbol.
      Returns:
      whether the given barcode type supports placing the human readable text above the barcode symbol
      See Also:

    • setTextOnTop

      public void setTextOnTop(boolean onTop)
      Sets whether the human readable text is to be placed above the barcode symbol.

      This must be supported by the given barcode type. See: supportsTextOnTop()

      Parameters:
      onTop - true to place the human readable text above the barcode symbol, false to place it below

    • isTextOnTop

      public boolean isTextOnTop()
      Returns whether the human readable text is placed above the barcode symbol.
      Returns:
      whether the human readable text is placed above the barcode symbol

    • setTextOffset

      public void setTextOffset(double offset)
      Sets the vertical offset for the human readable text relative to the barcode symbol.

      Positive values increase the distance between the text and the symbol, while negative values decrease it.

      Parameters:
      offset - the vertical offset for the human readable text

    • getTextOffset

      public double getTextOffset()
      Returns the vertical offset for the human readable text relative to the barcode symbol.
      Returns:
      the vertical offset for the human readable text relative to the barcode symbol

    • setFont

      public void setFont(Font font)
      Sets the font to be used for drawing the human readable text in the barcode.

      If set to null (default), the font assigned to the Graphics2D context will be used.

      Note: If automatic font size adjustment is enabled (see setFontSizeAdjusted), the size property of the specified font will be ignored.

      Parameters:
      font - the font for the human readable text, or null to use the font assigned to the Graphics2D context

    • getFont

      public Font getFont()
      Returns the font to be used for drawing the human readable text in the barcode.
      Returns:
      the font to be used for drawing the human readable text in the barcode

    • setFontSizeAdjusted

      public void setFontSizeAdjusted(boolean b)
      Sets whether the font size is to be automatically adjusted based on the size of the barcode symbol.

      The default is false.

      Parameters:
      b - true to automatically adjust the font size, false to keep the font size constant

    • isFontSizeAdjusted

      public boolean isFontSizeAdjusted()
      Returns whether the font size is automatically adjusted based on the size of the barcode symbol.
      Returns:
      whether the font size is automatically adjusted based on the size of the barcode symbol

    • supportsAutoCompletion

      public boolean supportsAutoCompletion()
      Returns whether the given barcode type supports auto-completion.

      The returned value indicates whether the autoComplete parameter in the setContent method has any effect.

      Returns:
      whether the given barcode type supports auto-completion

    • supportsOptionalChecksum

      public boolean supportsOptionalChecksum()
      Returns whether the given barcode type supports an optional checksum.

      The returned value indicates whether the appendOptionalChecksum parameter in the setContent method has any effect.

      Returns:
      whether the given barcode type supports an optional checksum

    • setOptionalChecksumVisible

      public void setOptionalChecksumVisible(boolean visible)
      Sets whether the optional checksum, if encoded in the barcode, is to be visible within the human readable text.
      Parameters:
      visible - true to display the optional checksum in the human readable text, false to hide it

    • isOptionalChecksumVisible

      public boolean isOptionalChecksumVisible()
      Returns whether the optional checksum, if encoded in the barcode, is visible within the human readable text.
      Returns:
      whether the optional checksum, if encoded in the barcode, is visible within the human readable text

    • supportsRatio

      public boolean supportsRatio()
      Returns whether the given barcode type supports setting the width ratio between wide and narrow bars in the barcode symbol.

      This feature is used in two-width barcode types such as Interleaved 2 of 5 (ITF), Code 39, Code 11 and Codabar.

      Returns:
      whether the given barcode type supports setting the width ratio between wide and narrow bars in the barcode symbol
      See Also:

    • setRatio

      public void setRatio(float ratio)
      Sets the width ratio between wide and narrow bars in two-width barcode types.

      The value must be in the range 2.0F to 3.0F, corresponding to ratios of 2.0:1 to 3.0:1. Values outside this range are automatically clamped. If not explicitly set, the default ratio is 2.5:1.

      This must be supported by the given barcode type. See: supportsRatio()

      Parameters:
      ratio - width ratio between wide and narrow bars

    • getRatio

      public float getRatio()
      Returns the width ratio between wide and narrow bars in two-width barcode types.
      Returns:
      the width ratio between wide and narrow bars in two-width barcode types

    • draw

      public void draw(Graphics2D g2d, double x, double y, double w, double h, double dotSize, double moduleSize, double barWidthCorrection)
      Draws the barcode symbol.

      Special attention is paid to the quality and, consequently, the later readability of the resulting barcode. This is mainly ensured by the following three parameters:

      dotSize - Specifies the size of a single point on the output medium, calculated from its resolution. For a printer, this should be the size of a dot, determined by the printer's resolution (DPI). For a bitmap image, it should be the "physical" size of a pixel, calculated from the pixel density (PPI). The value should be specified in the same unit as the other parameters. When using millimeters, for a resolution of 300 DPI/PPI, the formula would be: 25.4 / 300. When using inches: 1 / 300. This adjustment may be negligible in high-resolution output scenarios, where the value can be set to 0.0.

      Note: For 1D barcodes, which mainly consist of vertical bars, only one of the two resolutions is relevant. For example, when printing a 1D barcode at a 90° or 270° angle, the vertical resolution is crucial as the bar widths must be adjusted to it. Similarly, at a 0° or 180° angle, the horizontal resolution is important.

      moduleSize - Allows it to specify a fixed size of the modules (bars), that will affect the overall width of the barcode symbol. If set to 0.0, the method will automatically calculate an appropriate module size based on the width of the bounding box and the value of dotSize. In any case, if dotSize is greater than 0.0, the module size is adjusted to ensure that each module has a size that is a multiple of dotSize.

      barWidthCorrection - Adjusts the size of the modules (bars) of the barcode symbol. A positive value increases the size of the modules, while a negative value reduces them. For example, in the case of a printer, where ink bleeding may occur, a negative value may be necessary to compensate for the ink bleeding and ensure accurate module size. Similarly, for output scenarios where undesirable effects don't occur, the value can be set to 0.0.

      Parameters:
      g2d - the graphics context to draw on
      x - the x-coordinate of the top-left corner of the bounding box
      y - the y-coordinate of the top-left corner of the bounding box
      w - the width of the bounding box
      h - the height of the bounding box
      dotSize - the size of a single point on the output medium or 0.0
      moduleSize - the size of each module (bar) of the barcode symbol or 0.0
      barWidthCorrection - the bar width correction factor or 0.0

    • draw

      public void draw(Graphics2D g2d, double x, double y, double w, double h)
      Draws the barcode symbol.

      This method variant with a shortened parameter list does not consider any quality settings. It is typically suitable for printing on laser printers or exporting as vector graphics.

      Please refer to the main draw method for a detailed parameter description.

      Parameters:
      g2d - the graphics context to draw on
      x - the x-coordinate of the top-left corner of the bounding box
      y - the y-coordinate of the top-left corner of the bounding box
      w - the width of the bounding box
      h - the height of the bounding box

    • draw

      public void draw(Graphics2D g2d, double x, double y, double w, double h, double barWidthCorrection)
      Draws the barcode symbol.

      This method variant with a shortened parameter list only considers barWidthCorrection from the quality settings and uses 0.0 for the rest.

      Please refer to the main draw method for a detailed parameter description.

      Parameters:
      g2d - the graphics context to draw on
      x - the x-coordinate of the top-left corner of the bounding box
      y - the y-coordinate of the top-left corner of the bounding box
      w - the width of the bounding box
      h - the height of the bounding box
      barWidthCorrection - the bar width correction factor or 0.0

    • clone

      public Barcode clone()
      Returns a copy of this object.

      The returned copy is independent of the original and can be modified without affecting it. All instance members are either primitive or immutable types, or will be automatically rebuilt when any of the instance's properties change. Thus, the copy can be handled as if it were a "deep copy".

      Overrides:
      clone in class Object
      Returns:
      a copy of this object