java.lang.Object
- ca.cgjennings.apps.arkham.deck.PaperSets

```
public final class PaperSets
extends java.lang.Object
```
Organizes the available paper sizes into various sets broken down by characteristics and allows registration of new paper sizes. Strange Eons maintains several sets of paper sizes for different purposes. Using this class you can request all of the available paper sizes that match a particular description. The description is defined using a map. The map contains keys for properties that you are interested in matching, and each key maps to a value describing the attribute that a matching paper will have. In addition to this general matching capability, some static methods are provided to look up commonly used sets. The papers that match a given request will be described using instances of the PaperProperties class.

Since:

3.0

Author:

Chris Jennings

Field Summary

Fields
Modifier and Type	Field	Description
`static java.lang.Object`	`KEY_CONCRETENESS`	Add this key to the request map to specify whether papers should be physical or virtual.
`static java.lang.Object`	`KEY_GAME`	Add this key to the request map to specify the game to which the paper belongs.
`static java.lang.Object`	`KEY_MAXIMUM_SIZE`	Add this key with a value of type `Number` to specify a maximum size (in points).
`static java.lang.Object`	`KEY_MINIMUM_SIZE`	Add this key with a value of type `Number` to specify a minimum size (in points).
`static java.lang.Object`	`KEY_ORIENTATION`	Add this key to the request map to specify whether papers should have portrait or landscape orientation.
`static java.lang.Object`	`KEY_ORIGIN`	Add this key to the request map to specify whether papers from the built-in, user-defined, or temporary groups should be included.
`static java.lang.Object`	`KEY_SMALLER_THAN`	Add this key with a value of type `PaperProperties` to specify that all returned papers must have a smaller area than the specified target.
`static java.lang.Object`	`VALUE_CONCRETENESS_PHYSICAL`	Value for papers that represent a true physical paper size, such as A4 or Letter.
`static java.lang.Object`	`VALUE_CONCRETENESS_VIRTUAL`	Value for papers that represent a virtual paper size, like the size of a board for a board game.
`static java.lang.Object`	`VALUE_DONT_CARE`	Any key can be mapped to this value to indicate that it should not be considered.
`static java.lang.Object`	`VALUE_ORIENTATION_LANDSCAPE`	Value to request paper sizes with landscape orientation (wider than they are tall).
`static java.lang.Object`	`VALUE_ORIENTATION_PORTRAIT`	Value to request paper sizes with portrait orientation (taller than they are wide).
`static java.lang.Object`	`VALUE_ORIGIN_BUILT_IN`	Value for the default paper sizes that come built into Strange Eons.
`static java.lang.Object`	`VALUE_ORIGIN_TEMPORARY`	Value for paper sizes that have been registered as temporary papers by plug-ins.
`static java.lang.Object`	`VALUE_ORIGIN_USER_DEFINED`	Value for paper sizes that the user has defined as custom paper sizes.

Method Summary

All Methods Static Methods Concrete Methods
Modifier and Type	Method	Description
`static void`	`addTemporaryPaper(java.lang.String name, double widthInPoints, double heightInPoints, double marginInPoints, double gridInPoints, boolean isPhysicalPaperSize, Game game)`	Temporarily adds a paper size that will last until the application exits.
`static javax.swing.ListCellRenderer<PaperProperties>`	`createListCellRenderer()`	A utility method that returns a new list cell renderer suitable for displaying a list of paper types.
`static PaperProperties`	`findBestPaper(double targetWidth, double targetHeight, java.util.Set<PaperProperties> candidates)`	Returns the paper in the candidate set that is the closest match for the target size and orientation.
`static PaperProperties`	`findBestPaper(PaperProperties target, java.util.Set<PaperProperties> candidates)`	Returns the paper type most similar to the specified target of those candidates in the provided set.
`static java.util.Set<PaperProperties>`	`getBuiltInPapers()`	Returns a set of all built-in papers.
`static PaperProperties`	`getDefaultPaper(java.util.Set<PaperProperties> candidates)`	Returns the paper type in the specified set that most closely matches the platform-dependant default paper size.
`static java.util.Set<PaperProperties>`	`getMatchingPapers(java.util.Map<?,?> criteria)`	Returns an ordered set of all of the paper types that match the specified criteria.
`static java.util.Set<PaperProperties>`	`getTemporaryPapers()`	Returns a set of all currently registered temporary papers.
`static java.util.Set<PaperProperties>`	`getUserDefinedPapers()`	Returns a set of all user-defined paper types at the time that the method is called.
`static java.util.Set<PaperProperties>`	`modelToSet(javax.swing.ListModel<PaperProperties> model)`	Creates a set of paper types that match the contents of the specified list or combo box model (`ComboBoxModel` extends `ListModel`).
`static javax.swing.DefaultComboBoxModel<PaperProperties>`	`setToComboBoxModel(java.util.Set<PaperProperties> papers)`	Returns a model suitable for use in combo boxes that allows selection from the specified set of paper types.
`static javax.swing.DefaultListModel<PaperProperties>`	`setToListModel(java.util.Set<PaperProperties> papers)`	Returns a model suitable for use in `JList`s that allows selection from the specified set of paper types.
`static void`	`setUserDefinedPapers(java.util.Set<PaperProperties> papers)`	Replaces the current set of user-defined paper types with the specified set.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - KEY_CONCRETENESS
```
public static final java.lang.Object KEY_CONCRETENESS
```
    Add this key to the request map to specify whether papers should be physical or virtual.
  - VALUE_CONCRETENESS_PHYSICAL
```
public static final java.lang.Object VALUE_CONCRETENESS_PHYSICAL
```
    Value for papers that represent a true physical paper size, such as A4 or Letter.
  - VALUE_CONCRETENESS_VIRTUAL
```
public static final java.lang.Object VALUE_CONCRETENESS_VIRTUAL
```
    Value for papers that represent a virtual paper size, like the size of a board for a board game. These sizes are used to guide design rather than representing the actual size of the paper that will be printed on. Typically, decks that use virtual paper sizes are printed by splitting the virtual paper over multiple physical pages.
  - KEY_ORIGIN
```
public static final java.lang.Object KEY_ORIGIN
```
    Add this key to the request map to specify whether papers from the built-in, user-defined, or temporary groups should be included.
  - VALUE_ORIGIN_BUILT_IN
```
public static final java.lang.Object VALUE_ORIGIN_BUILT_IN
```
    Value for the default paper sizes that come built into Strange Eons.
  - VALUE_ORIGIN_TEMPORARY
```
public static final java.lang.Object VALUE_ORIGIN_TEMPORARY
```
    Value for paper sizes that have been registered as temporary papers by plug-ins.
    
    See Also:
    
    addTemporaryPaper(java.lang.String, double, double, double, double, boolean, gamedata.Game)
  - VALUE_ORIGIN_USER_DEFINED
```
public static final java.lang.Object VALUE_ORIGIN_USER_DEFINED
```
    Value for paper sizes that the user has defined as custom paper sizes.
  - KEY_ORIENTATION
```
public static final java.lang.Object KEY_ORIENTATION
```
    Add this key to the request map to specify whether papers should have portrait or landscape orientation.
  - VALUE_ORIENTATION_LANDSCAPE
```
public static final java.lang.Object VALUE_ORIENTATION_LANDSCAPE
```
    Value to request paper sizes with landscape orientation (wider than they are tall).
  - VALUE_ORIENTATION_PORTRAIT
```
public static final java.lang.Object VALUE_ORIENTATION_PORTRAIT
```
    Value to request paper sizes with portrait orientation (taller than they are wide).
  - KEY_GAME
```
public static final java.lang.Object KEY_GAME
```
    Add this key to the request map to specify the game to which the paper belongs. The value is an instance of Game. If set, it will filter out papers that were registered for any other game, but not papers that were registered for all games. That is, the papers in the returned set will either not be tied to a particular game, or will be tied to the specified game. If the value is VALUE_DONT_CARE (the default), then all papers will match regardless of game. If the value is Game.getAllGamesInstance(), then the papers in the returned set will not be associated with a particular game.
  - KEY_MAXIMUM_SIZE
```
public static final java.lang.Object KEY_MAXIMUM_SIZE
```
    Add this key with a value of type Number to specify a maximum size (in points). All matching papers will have both a width and a height that is less than or equal to this value.
  - KEY_MINIMUM_SIZE
```
public static final java.lang.Object KEY_MINIMUM_SIZE
```
    Add this key with a value of type Number to specify a minimum size (in points). All matching papers will have both a width and a height that is greater than or equal to this value.
  - KEY_SMALLER_THAN
```
public static final java.lang.Object KEY_SMALLER_THAN
```
    Add this key with a value of type PaperProperties to specify that all returned papers must have a smaller area than the specified target.
  - VALUE_DONT_CARE
```
public static final java.lang.Object VALUE_DONT_CARE
```
    Any key can be mapped to this value to indicate that it should not be considered. This is also the default if a key is not present in the map.
- Method Detail
  - getDefaultPaper
```
public static PaperProperties getDefaultPaper(java.util.Set<PaperProperties> candidates)
```
    Returns the paper type in the specified set that most closely matches the platform-dependant default paper size. If the set is null, the set of built-in, physical papers will be used.
    
    Returns:
    
    of the candidates, the type that most closely matches the default paper size
  - findBestPaper
```
public static PaperProperties findBestPaper(PaperProperties target,
                                            java.util.Set<PaperProperties> candidates)
```
    Returns the paper type most similar to the specified target of those candidates in the provided set. This method will only return null if the set of candidates is empty.
    
    Returns:
    
    of the candidates, the type that most closely matches the default paper size
    
    Throws:
    
    java.lang.NullPointerException - if the target or candidate set is null, or if the candidate set contains null
  - findBestPaper
```
public static PaperProperties findBestPaper(double targetWidth,
                                            double targetHeight,
                                            java.util.Set<PaperProperties> candidates)
```
    Returns the paper in the candidate set that is the closest match for the target size and orientation. If the width is greater then the height, then only a landscape paper amongst the candidates will match. Otherwise, only a portrait candidate will match. If there is no paper with the correct orientation, null is returned. Otherwise, the paper closest in size with the correct orientation is returned.
    
    Parameters:
    
    targetWidth - the paper width to match, in points
    
    targetHeight - the paper height to match, in points
    
    candidates - the set of papers to match against
    
    Returns:
    
    the closest size match with the correct orientation, or null
    
    Throws:
    
    java.lang.NullPointerException - if the candidate set is null or if the candidate set contains null
  - getBuiltInPapers
```
public static java.util.Set<PaperProperties> getBuiltInPapers()
```
    Returns a set of all built-in papers.
    
    Returns:
    
    a set of the built-in paper types
  - getTemporaryPapers
```
public static java.util.Set<PaperProperties> getTemporaryPapers()
```
    Returns a set of all currently registered temporary papers.
    
    Returns:
    
    a set of all temporary papers that have been registered with addTemporaryPaper(java.lang.String, double, double, double, double, boolean, gamedata.Game).
  - addTemporaryPaper
```
public static void addTemporaryPaper(java.lang.String name,
                                     double widthInPoints,
                                     double heightInPoints,
                                     double marginInPoints,
                                     double gridInPoints,
                                     boolean isPhysicalPaperSize,
                                     Game game)
```
    Temporarily adds a paper size that will last until the application exits. This is used by plug-ins to add special paper sizes that are only relevant as long as the plug-in is installed. A common case is the plug-in for a game adding virtual paper sizes to represent expansion boards for the game.
    There is no need to add separate portrait and landscape versions of the paper size; both will be generated automatically. Moreover, it does not matter if the width and height parameters are supplied in a portrait configuration or a landscape configuration.
    The value of marginInPoints determines the size of the margin, which is used as a visual cue for the designer (it does not prevent the placement of objects, although most printers cannot print all the way to their edges). The value of marginInPoints may be 0 to indicate no margin.
    The value of gridInPoints determines the spacing of a set of equidistant grid lines. Components that are not snapped to other components will normally snap to the nearest half-grid line. Either or both of these values may be less than 0, in which case default values will be used. If name starts with an at sign (@), then the rest of the string is used as an interface language key to look up a localized name.
    
    Parameters:
    
    name - the name to use for this paper type, localized if possible
    
    widthInPoints - the width of the paper, in points (1/72 inch)
    
    heightInPoints - the height of the paper, in points
    
    marginInPoints - the visual margin provided around the page in the deck editor, in points
    
    gridInPoints - the spacing of the grid in the deck editor, in points
    
    isPhysicalPaperSize - if true, then this represents an actual paper size; otherwise, it represents a size that is convenient to design for, like an expansion board
    
    Throws:
    
    java.lang.NullPointerException - if name is null
    
    java.lang.IllegalArgumentException - if name is empty or contains only whitespace, if either dimension is not in the range 0 < d < PaperProperties.MAX_PAPER_SIZE, or if gridInPoints is 0
  - getUserDefinedPapers
```
public static java.util.Set<PaperProperties> getUserDefinedPapers()
```
    Returns a set of all user-defined paper types at the time that the method is called.
    
    Returns:
    
    a set of user-defined papers
  - setUserDefinedPapers
```
public static void setUserDefinedPapers(java.util.Set<PaperProperties> papers)
```
    Replaces the current set of user-defined paper types with the specified set. It is strongly recommended that the specified set be of a type that uses an ordered iterator, such as LinkedHashSet, as this will determine the order that the paper types will be written in. (Ordered sets are always returned by the methods in this class.)
    Important: This set should include only the portrait or landscape version of each paper size. Portrait and landscape pairs will be generated automatically when the list is read in using getUserDefinedPapers().
    
    Parameters:
    
    papers - the set of paper properties that will replace the current user-defined paper set
    
    Throws:
    
    java.lang.NullPointerException - if the set is null or if it contains null
  - getMatchingPapers
```
public static java.util.Set<PaperProperties> getMatchingPapers(java.util.Map<?,?> criteria)
```
    Returns an ordered set of all of the paper types that match the specified criteria. The criteria are specified as a map using the keys and values defined in this class.
    
    Parameters:
    
    criteria - a map of the criteria to match
    
    Returns:
    
    a set of the papers that match the specified criteria
  - setToComboBoxModel
```
public static javax.swing.DefaultComboBoxModel<PaperProperties> setToComboBoxModel(java.util.Set<PaperProperties> papers)
```
    Returns a model suitable for use in combo boxes that allows selection from the specified set of paper types.
    
    Parameters:
    
    papers - the set to create a model for
    
    Returns:
    
    a combo box model of the requested papers
    
    Throws:
    
    java.lang.NullPointerException - if the paper set is null
  - setToListModel
```
public static javax.swing.DefaultListModel<PaperProperties> setToListModel(java.util.Set<PaperProperties> papers)
```
    Returns a model suitable for use in JLists that allows selection from the specified set of paper types.
    
    Parameters:
    
    papers - the set to create a model for
    
    Returns:
    
    a list model of the requested papers
    
    Throws:
    
    java.lang.NullPointerException - if the paper set is null
  - modelToSet
```
public static java.util.Set<PaperProperties> modelToSet(javax.swing.ListModel<PaperProperties> model)
```
    Creates a set of paper types that match the contents of the specified list or combo box model (ComboBoxModel extends ListModel).
    
    Parameters:
    
    model - the model to create a set for
    
    Returns:
    
    a set with the same papers as the model
    
    Throws:
    
    java.lang.NullPointerException - if the model is null
  - createListCellRenderer
```
public static javax.swing.ListCellRenderer<PaperProperties> createListCellRenderer()
```
    A utility method that returns a new list cell renderer suitable for displaying a list of paper types. Using this method ensures consistency for paper lists and combo boxes.
    
    Returns:
    
    a list cell renderer for sets of paper properties instances

Class PaperSets

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

KEY_CONCRETENESS

VALUE_CONCRETENESS_PHYSICAL

VALUE_CONCRETENESS_VIRTUAL

KEY_ORIGIN

VALUE_ORIGIN_BUILT_IN

VALUE_ORIGIN_TEMPORARY

VALUE_ORIGIN_USER_DEFINED

KEY_ORIENTATION

VALUE_ORIENTATION_LANDSCAPE

VALUE_ORIENTATION_PORTRAIT

KEY_GAME

KEY_MAXIMUM_SIZE

KEY_MINIMUM_SIZE

KEY_SMALLER_THAN

VALUE_DONT_CARE

Method Detail

getDefaultPaper

findBestPaper

findBestPaper

getBuiltInPapers

getTemporaryPapers

addTemporaryPaper

getUserDefinedPapers

setUserDefinedPapers

getMatchingPapers

setToComboBoxModel

setToListModel

modelToSet

createListCellRenderer