Upstream/HolographicDisplays
1
0
Fork 0
mirror of https://github.com/filoghost/HolographicDisplays.git synced 2024-12-28 03:37:36 +01:00
Code Issues Projects Releases Wiki Activity

Improve API Javadocs

Browse Source
This commit is contained in:
filoghost 2022-06-04 19:11:17 +02:00
parent 4431605a3a
commit d58adb7db8
22 changed files with 558 additions and 71 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

116
api/src/main/java/me/filoghost/holographicdisplays/api/HolographicDisplaysAPI.java
View File

@ -13,7 +13,9 @@ import me.filoghost.holographicdisplays.api.placeholder.GlobalPlaceholderReplace
import me.filoghost.holographicdisplays.api.placeholder.IndividualPlaceholder;
import me.filoghost.holographicdisplays.api.placeholder.IndividualPlaceholderFactory;
import me.filoghost.holographicdisplays.api.placeholder.IndividualPlaceholderReplaceFunction;
import me.filoghost.holographicdisplays.api.placeholder.Placeholder;
import org.bukkit.Location;
import org.bukkit.entity.Player;
import org.bukkit.plugin.Plugin;
import org.jetbrains.annotations.NotNull;
@ -21,22 +23,23 @@ import java.util.Collection;
/**
* Main entry point for accessing the Holographic Displays API.
* <p>
* Each API instance only manages the holograms and the placeholders of a specific plugin, see {@link #get(Plugin)}.
*
* @since 1
*/
public interface HolographicDisplaysAPI {
/**
* Returns the API version number, which is increased every time the API changes. This number is used to check if a
* certain method or class (which may have been added later) is present or not.
* Returns the API version number, which is increased every time the API changes.
* <p>
* All public API classes and methods are documented with the Javadoc tag {@code @since}, indicating in which API
* version that element was introduced.
* <p>
* It can be used it to require a minimum version, as features may be added (rarely removed) in future versions. The
* first version of the API is 1.
* This number can be used it to require a minimum version, as features may be added (rarely removed) in future
* versions. The first version of the API is 1.
* <p>
* The API version is independent of the normal plugin version.
* The API version is unrelated to the standard plugin version.
*
* @return the current API version
* @since 1
@ -61,57 +64,134 @@ public interface HolographicDisplaysAPI {
}
/**
* Creates a hologram at given location.
* Creates a hologram.
*
* @param location the location where it will appear
* @param location the initial location of the hologram
* @return the created hologram
* @since 1
*/
@NotNull Hologram createHologram(@NotNull Location location);
/**
* Creates a hologram.
*
* @param position the initial position of the hologram
* @return the created hologram
* @since 1
*/
@NotNull Hologram createHologram(@NotNull Position position);
/**
* Returns all the active holograms. A hologram is no longer active after {@link Hologram#delete()} is invoked.
* Returns all the holograms. Deleted holograms are not included.
*
* @return an immutable collection of active holograms
* @return an immutable copy of all the holograms
* @since 1
*/
@NotNull Collection<Hologram> getHolograms();
/**
* Deletes all the holograms. Equivalent to invoking {@link Hologram#delete()} on each hologram.
*
* @since 1
*/
void deleteHolograms();
/**
* Registers a new global placeholder. Any previously registered element (global or individual) with the same
* identifier is overwritten. See {@link GlobalPlaceholder} to know more about global placeholders.
* <p>
* This is a simplified method to register a placeholder by providing separately its replace function for
* {@link GlobalPlaceholder#getReplacement(String)} and a fixed refresh interval for
* {@link Placeholder#getRefreshIntervalTicks()}
*
* @param identifier the case-insensitive identifier of the placeholder
* @param refreshIntervalTicks the minimum interval in ticks between invocations of the replace function
* (when the placeholder is in use), see {@link Placeholder#getRefreshIntervalTicks()}
* @param replaceFunction the callback function to provide the replacement text to display
* @since 1
*/
void registerGlobalPlaceholder(@NotNull String identifier, int refreshIntervalTicks, @NotNull GlobalPlaceholderReplaceFunction replaceFunction);
void registerGlobalPlaceholder(
@NotNull String identifier,
int refreshIntervalTicks,
@NotNull GlobalPlaceholderReplaceFunction replaceFunction);
/**
* Registers a new global placeholder. Any previously registered element (global or individual) with the same
* identifier is overwritten. See {@link GlobalPlaceholder} to know more about global placeholders.
*
* @param identifier the case-insensitive identifier of the placeholder
* @param placeholder the placeholder to register
* @since 1
*/
void registerGlobalPlaceholder(@NotNull String identifier, @NotNull GlobalPlaceholder placeholder);
/**
* Registers a new global placeholder factory. Any previously registered element (global or individual) with the
* same identifier is overwritten. See {@link GlobalPlaceholder} to know more about global placeholders.
* <p>
* This method is more complex and not usually needed: it is necessary if parsing the argument of the placeholder is
* performance intensive, for example a mathematical expression or a JSON string.
* <p>
* See {@link GlobalPlaceholderFactory} to know more about global placeholder factories.
*
* @param identifier the case-insensitive identifier of the placeholder factory
* @param placeholderFactory the placeholder factory to register
* @since 1
*/
void registerGlobalPlaceholderFactory(@NotNull String identifier, @NotNull GlobalPlaceholderFactory placeholderFactory);
void registerGlobalPlaceholderFactory(
@NotNull String identifier,
@NotNull GlobalPlaceholderFactory placeholderFactory);
/**
* Registers a new individual placeholder. Any previously registered element (global or individual) with the
* same identifier is overwritten. See {@link IndividualPlaceholder} to know more about individual placeholders.
* <p>
* This is a simplified method to register a placeholder by providing separately its replace function for
* {@link IndividualPlaceholder#getReplacement(Player, String)} and a fixed refresh interval for
* {@link Placeholder#getRefreshIntervalTicks()}
*
* @param identifier the case-insensitive identifier of the placeholder
* @param refreshIntervalTicks the minimum interval in ticks between invocations of the replace function for
* each player (when the placeholder is in use), see {@link Placeholder#getRefreshIntervalTicks()}
* @param replaceFunction the callback function to provide the replacement text to display
* @since 1
*/
void registerIndividualPlaceholder(@NotNull String identifier, int refreshIntervalTicks, @NotNull IndividualPlaceholderReplaceFunction replaceFunction);
void registerIndividualPlaceholder(
@NotNull String identifier,
int refreshIntervalTicks,
@NotNull IndividualPlaceholderReplaceFunction replaceFunction);
/**
* Registers a new individual placeholder. Any previously registered element (global or individual) with the same
* identifier is overwritten. See {@link IndividualPlaceholder} to know more about individual placeholders.
*
* @param identifier the case-insensitive identifier of the placeholder
* @param placeholder the placeholder to register
* @since 1
*/
void registerIndividualPlaceholder(@NotNull String identifier, @NotNull IndividualPlaceholder placeholder);
/**
* Registers a new individual placeholder factory. Any previously registered element (global or individual) with the
* same identifier is overwritten. See {@link IndividualPlaceholder} to know more about individual placeholders.
* <p>
* This method is more complex and not usually needed: it is necessary if parsing the argument of the placeholder is
* performance intensive, for example a mathematical expression or a JSON string.
* <p>
* See {@link IndividualPlaceholderFactory} to know more about individual placeholder factories.
*
* @param identifier the case-insensitive identifier of the placeholder factory
* @param placeholderFactory the placeholder factory to register
* @since 1
*/
void registerIndividualPlaceholderFactory(@NotNull String identifier, @NotNull IndividualPlaceholderFactory placeholderFactory);
void registerIndividualPlaceholderFactory(
@NotNull String identifier,
@NotNull IndividualPlaceholderFactory placeholderFactory);
/**
* Returns if a placeholder with a given identifier is registered.
*
* @param identifier the case-insensitive identifier of the placeholder
* @since 1
*/
boolean isRegisteredPlaceholder(@NotNull String identifier);
@ -119,23 +199,21 @@ public interface HolographicDisplaysAPI {
/**
* Returns all the registered placeholder identifiers.
*
* @return a collection of placeholder identifiers
* @return an immutable copy of the registered placeholder identifiers
* @since 1
*/
@NotNull Collection<String> getRegisteredPlaceholders();
/**
* Unregisters a placeholder.
* Unregisters the placeholder with a given identifier.
*
* @param identifier the identifier of the placeholder to remove
* @param identifier the identifier of the placeholder to unregister, case-insensitive
* @since 1
*/
void unregisterPlaceholder(@NotNull String identifier);
/**
* Resets and removes all the registered placeholders.
* <p>
* Can be useful to reset placeholders before registering all of them.
* Unregisters all placeholders.
*
* @since 1
*/

205
api/src/main/java/me/filoghost/holographicdisplays/api/Position.java
View File

@ -14,72 +14,277 @@ import org.bukkit.util.Vector;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Represents an immutable 3-dimensional position in a world. Differently from a {@link Location} it holds a reference
* to a world's name instead of a {@link World} object directly, making it suitable for unloaded worlds. Another
* difference is the lack of yaw and pitch.
*
* @since 1
*/
public interface Position {
/**
* Returns the position with the given world and coordinates.
*
* @param world the world
* @param x the X coordinate
* @param y the Y coordinate
* @param z the Z coordinate
* @return the created position
* @since 1
*/
static @NotNull Position of(@NotNull World world, double x, double y, double z) {
return HolographicDisplaysAPIProvider.getImplementation().createPosition(world, x, y, z);
}
/**
* Returns the position with the given world and coordinates.
*
* @param worldName the name of the world
* @param x the X coordinate
* @param y the Y coordinate
* @param z the Z coordinate
* @return the created position
* @since 1
*/
static @NotNull Position of(@NotNull String worldName, double x, double y, double z) {
return HolographicDisplaysAPIProvider.getImplementation().createPosition(worldName, x, y, z);
}
/**
* Returns the position from a Location.
*
* @param location the location from which to obtain the position
* @return the created position
* @since 1
*/
static @NotNull Position of(@NotNull Location location) {
return HolographicDisplaysAPIProvider.getImplementation().getPosition(location);
}
/**
* Returns the position of an entity.
*
* @param entity the entity from which to obtain the position
* @return the created position
* @since 1
*/
static @NotNull Position of(@NotNull Entity entity) {
return HolographicDisplaysAPIProvider.getImplementation().getPosition(entity);
}
/**
* Returns the position of a block.
*
* @param block the block from which to obtain the position
* @return the created position
* @since 1
*/
static @NotNull Position of(@NotNull Block block) {
return HolographicDisplaysAPIProvider.getImplementation().getPosition(block);
}
/**
* Returns the name of the world of this position.
*
* @return the world name
* @since 1
*/
@NotNull String getWorldName();
/**
* Returns the X coordinate of this position.
*
* @return the X coordinate
* @since 1
*/
double getX();
/**
* Returns the Y coordinate of this position.
*
* @return the Y coordinate
* @since 1
*/
double getY();
/**
* Returns the Z coordinate of this position.
*
* @return the Z coordinate
* @since 1
*/
double getZ();
/**
* Returns the loaded world of this position or null if it's not loaded.
*
* @return the loaded world or null if not loaded
* @since 1
*/
@Nullable World getWorldIfLoaded();
/**
* Returns if this position is in the same world of another position.
*
* @param position the position to compare
* @return true if the world is the same, false otherwise
* @since 1
*/
boolean isInSameWorld(@NotNull Position position);
/**
* Returns if this position is in the same world of a Location.
*
* @param location the location to compare
* @return true if the world is the same, false otherwise
* @since 1
*/
boolean isInSameWorld(@NotNull Location location);
/**
* Returns if this position is in the same world of an entity.
*
* @param entity the entity to compare
* @return true if the world is the same, false otherwise
* @since 1
*/
boolean isInSameWorld(@NotNull Entity entity);
/**
* Returns if this position is in the given world.
*
* @param world the world to compare
* @return true if the world matches, false otherwise
* @since 1
*/
boolean isInWorld(@Nullable World world);
/**
* Returns if this position is in the given world name.
*
* @param worldName the world name to compare
* @return true if the world name matches, false otherwise
* @since 1
*/
boolean isInWorld(@Nullable String worldName);
/**
* Returns the X coordinate of the block in this position.
*
* @return the block's X coordinate
* @since 1
*/
int getBlockX();
/**
* Returns the Y coordinate of the block in this position.
*
* @return the block's Y coordinate
* @since 1
*/
int getBlockY();
/**
* Returns the Z coordinate of the block in this position.
*
* @return the block's Z coordinate
* @since 1
*/
int getBlockZ();
/**
* Returns a new position made by adding the given lengths to each coordinate.
*
* @param x the length to add to the X coordinate
* @param y the length to add to the Y coordinate
* @param z the length to add to the Z coordinate
* @since 1
*/
@NotNull Position add(double x, double y, double z);
/**
* Returns a new position made by subtracting the given lengths from each coordinate.
*
* @param x the length to subtract from the X coordinate
* @param y the length to subtract from the Y coordinate
* @param z the length to subtract from the Z coordinate
* @since 1
*/
@NotNull Position subtract(double x, double y, double z);
/**
* Returns the distance between this position and another position. Avoid repeatedly calling this method as it uses
* a costly square-root function, or consider using {@link #distanceSquared(Position)} instead.
*
* @param position the position from which to measure the distance
* @return the distance from the other position
* @since 1
*/
double distance(@NotNull Position position);
/**
* Returns the distance between this position and a Location. Avoid repeatedly calling this method as it uses
* a costly square-root function, or consider using {@link #distanceSquared(Location)} instead.
*
* @param location the location from which to measure the distance
* @return the distance from the Location
* @since 1
*/
double distance(@NotNull Location location);
/**
* Returns the distance between this position and an entity. Avoid repeatedly calling this method as it uses
* a costly square-root function, or consider using {@link #distanceSquared(Entity)} instead.
*
* @param entity the entity from which to measure the distance
* @return the distance from the entity
* @since 1
*/
double distance(@NotNull Entity entity);
/**
* Returns the squared distance between this position and another position.
*
* @param position the position from which to measure the distance
* @return the squared distance from the other position
* @since 1
*/
double distanceSquared(@NotNull Position position);
/**
* Returns the squared distance between this position and a Location.
*
* @param location the location from which to measure the distance
* @return the squared distance from the Location
* @since 1
*/
double distanceSquared(@NotNull Location location);
/**
* Returns the squared distance between this position and an entity.
*
* @param entity the entity from which to measure the distance
* @return the squared distance from the entity
* @since 1
*/
double distanceSquared(@NotNull Entity entity);
/**
* Returns a new Location derived from this position. <b>Warning</b>: if the world is not loaded, the Location will
* contain a null {@link World}, which can lead to unexpected errors.
*
* @return A new Location based on this position
* @since 1
*/
@NotNull Location toLocation();
/**
* Returns a new Vector derived from this position.
*
* @return a new Vector based on this position
* @since 1
*/
@NotNull Vector toVector();
}

30
api/src/main/java/me/filoghost/holographicdisplays/api/hologram/Hologram.java
View File

@ -12,24 +12,27 @@ import org.bukkit.World;
import org.jetbrains.annotations.NotNull;
/**
* Entity to manage a group of vertically aligned lines, which display floating text and items.
* To create one see {@link HolographicDisplaysAPI}.
* Group of one or more vertically aligned lines which appear as floating text lines and items. To create one see
* {@link HolographicDisplaysAPI#createHologram(Position)}.
* <p>
* The lines are displayed in a top to bottom order starting from the hologram position and going down.
*
* @since 1
*/
public interface Hologram {
/**
* Returns the editable list of lines.
* Returns the editable lines of this hologram.
*
* @return the editable lines
* @since 1
*/
@NotNull HologramLines getLines();
/**
* Returns the {@link VisibilitySettings} of this hologram.
* Returns the visibility settings.
*
* @return the VisibilitySettings of this hologram
* @return the visibility settings
* @since 1
*/
@NotNull VisibilitySettings getVisibilitySettings();
@ -53,7 +56,7 @@ public interface Hologram {
/**
* Moves the hologram to the given position.
*
* @param worldName the world name where the hologram should be moved
* @param worldName the name of the world where the hologram should be moved
* @param x the X coordinate
* @param y the Y coordinate
* @param z the Z coordinate
@ -81,28 +84,33 @@ public interface Hologram {
void setPosition(@NotNull Location location);
/**
* Returns the placeholder setting.
*
* @return the placeholder setting
* @since 1
*/
@NotNull PlaceholderSetting getPlaceholderSetting();
/**
* Changes the placeholder setting.
*
* @param placeholderSetting the new placeholder setting
* @since 1
*/
void setPlaceholderSetting(@NotNull PlaceholderSetting placeholderSetting);
/**
* Deletes this hologram. Editing or teleporting the hologram when deleted
* will throw an exception. Lines will be automatically cleared.
* You should remove all the references of the hologram after deletion.
* Deletes this hologram, clearing the lines. Editing or teleporting the hologram after deleting it throws an
* exception. A deleted hologram should no longer be referenced.
*
* @since 1
*/
void delete();
/**
* Checks if a hologram was deleted.
* Returns if this hologram is deleted.
*
* @return true if this hologram was deleted
* @return true if this hologram is deleted
* @since 1
*/
boolean isDeleted();

21
api/src/main/java/me/filoghost/holographicdisplays/api/hologram/HologramLines.java
View File

@ -13,14 +13,15 @@ import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* The editable list of lines of a hologram.
* The editable lines of a hologram, following a top to bottom order (first line is top one, last line is the bottom
* one).
*
* @since 1
*/
public interface HologramLines {
/**
* Adds a new text line at the end.
* Adds a new text line at the bottom.
*
* @param text the content of the line, see {@link TextHologramLine#setText(String)}
* @return the created line
@ -29,7 +30,7 @@ public interface HologramLines {
@NotNull TextHologramLine appendText(@Nullable String text);
/**
* Adds a new item line at the end.
* Adds a new item line at the bottom.
*
* @param itemStack the content of the line, see {@link ItemHologramLine#setItemStack(ItemStack)}
* @return the created line
@ -38,9 +39,9 @@ public interface HologramLines {
@NotNull ItemHologramLine appendItem(@Nullable ItemStack itemStack);
/**
* Inserts a new text line before the given index.
* Inserts a new text line before the line at the given index, shifting all the lines below.
*
* @param beforeIndex the index before which the line is inserted, 0 to insert as first
* @param beforeIndex the index before which the line should be inserted, 0 to insert on top
* @param text the content of the line, see {@link TextHologramLine#setText(String)}
* @return the created line
* @throws IndexOutOfBoundsException if the index is out of range (index &lt; 0 || index &gt;= size())
@ -49,9 +50,9 @@ public interface HologramLines {
@NotNull TextHologramLine insertText(int beforeIndex, @Nullable String text);
/**
* Inserts a new item line before the given index.
* Inserts a new item line before the line at the given index, shifting all the lines below.
*
* @param beforeIndex the index before which the line is inserted, 0 to insert as first
* @param beforeIndex the index before which the line should be inserted, 0 to insert on top
* @param itemStack the content of the line, see {@link ItemHologramLine#setItemStack(ItemStack)}
* @return the created line
* @throws IndexOutOfBoundsException if the index is out of range (index &lt; 0 || index &gt;= size())
@ -95,15 +96,15 @@ public interface HologramLines {
void clear();
/**
* Returns the amount of lines.
* Returns the current amount of lines.
*
* @return the amount of lines
* @return the current amount of lines
* @since 1
*/
int size();
/**
* The total height of the lines, including the gaps between them.
* The total height in blocks occupied by the lines, including the gaps between them.
*
* @return the total height of the lines
* @since 1

23
api/src/main/java/me/filoghost/holographicdisplays/api/hologram/PlaceholderSetting.java
View File

@ -5,10 +5,33 @@
*/
package me.filoghost.holographicdisplays.api.hologram;
/**
* The option to enable or disable placeholders inside the text lines of hologram.
*
* @see Hologram#setPlaceholderSetting(PlaceholderSetting)
* @since 1
*/
public enum PlaceholderSetting {
/**
* The default setting for placeholders (which is currently equivalent to {@link #DISABLE_ALL}).
*
* @since 1
*/
DEFAULT,
/**
* Enable all placeholders.
*
* @since 1
*/
ENABLE_ALL,
/**
* Disable all placeholders.
*
* @since 1
*/
DISABLE_ALL
}

38
api/src/main/java/me/filoghost/holographicdisplays/api/hologram/VisibilitySettings.java
View File

@ -9,7 +9,7 @@ import org.bukkit.entity.Player;
import org.jetbrains.annotations.NotNull;
/**
* Settings to manage the visibility of a hologram to players. Allows to set a global visibility and an individual
* Settings to manage the visibility of a hologram to players. Allows to set both a global visibility and an individual
* visibility for specific players.
*
* @since 1
@ -17,7 +17,10 @@ import org.jetbrains.annotations.NotNull;
public interface VisibilitySettings {
/**
* Returns the visibility of the hologram. The initial value is {@link Visibility#VISIBLE}.
* Returns the global visibility. This value only affects player which do not have an individual visibility (see
* {@link #setIndividualVisibility(Player, Visibility)}).
* <p>
* The initial value is {@link Visibility#VISIBLE}, which means that all players can see the hologram.
*
* @return the visibility
* @since 1
@ -25,8 +28,8 @@ public interface VisibilitySettings {
@NotNull Visibility getGlobalVisibility();
/**
* Sets the visibility of the hologram. This value only affects player which do not have an individual visibility
* (see {@link #setIndividualVisibility(Player, Visibility)}).
* Sets the global visibility. This value only affects player which do not have an individual visibility (see
* {@link #setIndividualVisibility(Player, Visibility)}).
*
* @param visibility the new visibility
* @since 1
@ -34,15 +37,16 @@ public interface VisibilitySettings {
void setGlobalVisibility(@NotNull Visibility visibility);
/**
* Sets the visibility for a specific player, overriding the global value of ({@link #getGlobalVisibility()}).
* The individual visibility value can be removed with {@link #removeIndividualVisibility(Player)}.
* Sets the visibility for a specific player, with precedence over the global visibility
* ({@link #getGlobalVisibility()}). The individual visibility value can be removed with
* {@link #removeIndividualVisibility(Player)}.
*
* @since 1
*/
void setIndividualVisibility(@NotNull Player player, @NotNull Visibility visibility);
/**
* Removes the individual visibility for a player. The visibility for the player would then be determined by the
* Removes the individual visibility for a player. The visibility for the player will then be determined by the
* global visibility ({@link #getGlobalVisibility()}).
*
* @since 1
@ -50,7 +54,8 @@ public interface VisibilitySettings {
void removeIndividualVisibility(@NotNull Player player);
/**
* Removes the individual visibility of all players which have one.
* Removes the individual visibility for all players. The visibility for all players will then be determined by the
* global visibility ({@link #getGlobalVisibility()}).
*
* @since 1
*/
@ -58,7 +63,7 @@ public interface VisibilitySettings {
/**
* Checks if a hologram is visible to a player, taking into account both the global visibility and the individual
* visibility of the player (if set).
* visibility for the player (if set).
*
* @param player the player
* @return if the player can see the hologram
@ -68,11 +73,24 @@ public interface VisibilitySettings {
/**
* The available statuses for the visibility of a hologram.
* The visibility status of a hologram, which can be set both globally and for individual players.
*
* @since 1
*/
enum Visibility {
/**
* The hologram is visible.
*
* @since 1
*/
VISIBLE,
/**
* The hologram is not visible.
*
* @since 1
*/
HIDDEN
}

7
api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ClickableHologramLine.java
View File

@ -8,7 +8,8 @@ package me.filoghost.holographicdisplays.api.hologram.line;
import org.jetbrains.annotations.Nullable;
/**
* A hologram line that can be clicked (left or right click).
* A hologram line that can be left-clicked or right-click. Currently, both {@link TextHologramLine} and
* {@link ItemHologramLine} are clickable.
*
* @since 1
*/
@ -17,7 +18,7 @@ public interface ClickableHologramLine extends HologramLine {
/**
* Returns the current click listener.
*
* @return the current click listener, null if not present
* @return the current click listener, null if absent
* @since 1
*/
@Nullable HologramLineClickListener getClickListener();
@ -25,7 +26,7 @@ public interface ClickableHologramLine extends HologramLine {
/**
* Sets the click listener.
*
* @param clickListener the new click listener, null to unset
* @param clickListener the new click listener, null to remove it
* @since 1
*/
void setClickListener(@Nullable HologramLineClickListener clickListener);

4
api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLine.java
View File

@ -6,8 +6,10 @@
package me.filoghost.holographicdisplays.api.hologram.line;
/**
* Interface to represent a line in a Hologram.
* A line of a hologram.
*
* @see TextHologramLine
* @see ItemHologramLine
* @since 1
*/
public interface HologramLine {

14
api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickEvent.java
View File

@ -7,8 +7,22 @@ package me.filoghost.holographicdisplays.api.hologram.line;
import org.bukkit.entity.Player;
/**
* The event of a player clicking on a {@link ClickableHologramLine}.
* <p>
* This is not a Bukkit event, the listener must be set with
* {@link ClickableHologramLine#setClickListener(HologramLineClickListener)}.
*
* @since 1
*/
public interface HologramLineClickEvent {
/**
* Returns the player who clicked on the line.
*
* @return the player who clicked
* @since 1
*/
Player getPlayer();
}

8
api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLineClickListener.java
View File

@ -8,7 +8,10 @@ package me.filoghost.holographicdisplays.api.hologram.line;
import org.jetbrains.annotations.NotNull;
/**
* Interface to handle clickable hologram lines.
* The listener class for {@link HologramLineClickEvent}.
* <p>
* This is not a Bukkit listener, it must be set with
* {@link ClickableHologramLine#setClickListener(HologramLineClickListener)}.
*
* @since 1
*/
@ -16,6 +19,9 @@ import org.jetbrains.annotations.NotNull;
public interface HologramLineClickListener {
/**
* Invoked when a player clicks on the clickable line.
*
* @param clickEvent the event data
* @since 1
*/
void onClick(@NotNull HologramLineClickEvent clickEvent);

14
api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupEvent.java
View File

@ -7,8 +7,22 @@ package me.filoghost.holographicdisplays.api.hologram.line;
import org.bukkit.entity.Player;
/**
* The event of a player being in pickup range of an {@link ItemHologramLine}.
* <p>
* This is not a Bukkit event, the listener must be set with
* {@link ItemHologramLine#setPickupListener(HologramLinePickupListener)}.
*
* @since 1
*/
public interface HologramLinePickupEvent {
/**
* Returns the player being in pickup range of the item line.
*
* @return the player in pickup range of the item line
* @since 1
*/
Player getPlayer();
}

10
api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/HologramLinePickupListener.java
View File

@ -8,7 +8,10 @@ package me.filoghost.holographicdisplays.api.hologram.line;
import org.jetbrains.annotations.NotNull;
/**
* Interface to handle hologram lines being picked up by players.
* The listener class for {@link HologramLinePickupEvent}.
* <p>
* This is not a Bukkit listener, it must be set with
* {@link ItemHologramLine#setPickupListener(HologramLinePickupListener)}.
*
* @since 1
*/
@ -16,6 +19,11 @@ import org.jetbrains.annotations.NotNull;
public interface HologramLinePickupListener {
/**
* Invoked when a player is being in pickup range of the item line. Note that this method is invoked repeatedly
* every tick until the player moves out of range, the listener is removed, the item line is no longer visible to
* the player, or the item line is removed.
*
* @param pickupEvent the event data
* @since 1
*/
void onPickup(@NotNull HologramLinePickupEvent pickupEvent);

14
api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/ItemHologramLine.java
View File

@ -9,22 +9,24 @@ import org.bukkit.inventory.ItemStack;
import org.jetbrains.annotations.Nullable;
/**
* A hologram line displaying an item.
*
* @since 1
*/
public interface ItemHologramLine extends ClickableHologramLine {
/**
* Returns the ItemStack of this ItemLine.
* Returns the currently displayed item.
*
* @return the ItemStack if this ItemLine.
* @return the current item
* @since 1
*/
@Nullable ItemStack getItemStack();
/**
* Sets the ItemStack for this ItemLine.
* Sets the displayed item.
*
* @param itemStack the new item, should not be null.
* @param itemStack the new item, null to display air
* @since 1
*/
void setItemStack(@Nullable ItemStack itemStack);
@ -32,7 +34,7 @@ public interface ItemHologramLine extends ClickableHologramLine {
/**
* Returns the current pickup listener.
*
* @return the current pickup listener, null if not present
* @return the current pickup listener, null if absent
* @since 1
*/
@Nullable HologramLinePickupListener getPickupListener();
@ -40,7 +42,7 @@ public interface ItemHologramLine extends ClickableHologramLine {
/**
* Sets the pickup listener.
*
* @param pickupListener the new pickup listener, null to unset
* @param pickupListener the new pickup listener, null to remove it
* @since 1
*/
void setPickupListener(@Nullable HologramLinePickupListener pickupListener);

6
api/src/main/java/me/filoghost/holographicdisplays/api/hologram/line/TextHologramLine.java
View File

@ -8,6 +8,8 @@ package me.filoghost.holographicdisplays.api.hologram.line;
import org.jetbrains.annotations.Nullable;
/**
* A hologram line displaying text.
*
* @since 1
*/
public interface TextHologramLine extends ClickableHologramLine {
@ -15,7 +17,7 @@ public interface TextHologramLine extends ClickableHologramLine {
/**
* Returns the currently displayed text.
*
* @return the currently displayed text.
* @return the current text
* @since 1
*/
@Nullable String getText();
@ -23,7 +25,7 @@ public interface TextHologramLine extends ClickableHologramLine {
/**
* Sets the displayed text.
*
* @param text the new displayed text.
* @param text the new text
* @since 1
*/
void setText(@Nullable String text);

3
api/src/main/java/me/filoghost/holographicdisplays/api/internal/HolographicDisplaysAPIProvider.java
View File

@ -14,6 +14,9 @@ import org.bukkit.entity.Entity;
import org.bukkit.plugin.Plugin;
import org.jetbrains.annotations.ApiStatus.Internal;
/**
* This class is used internally and can change without notice, do not use it.
*/
@Internal
public abstract class HolographicDisplaysAPIProvider {

15
api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholder.java
View File

@ -8,18 +8,25 @@ package me.filoghost.holographicdisplays.api.placeholder;
import org.jetbrains.annotations.Nullable;
/**
* A global placeholder that displays the same text to all players. See {@link Placeholder} for general information
* about placeholders.
*
* @since 1
*/
public interface GlobalPlaceholder extends Placeholder {
/**
* Callback for providing a placeholder replacement, given the argument of the placeholder (if present).
* Callback for providing a placeholder replacement for a given optional argument. The same replacement is shown to
* all players.
* <p>
* For example, the argument of {test} is null, the argument of {test: hello world} is the string "hello world".
* The argument is provided through the placeholder text: for example, the argument of {test} is null, the argument
* of {test: hello world} is the string "hello world".
* <p>
* <b>Warning</b>: this method should be performance efficient, as it may be invoked often.
* <b>Warning</b>: the implementation should be performance efficient, as it may be invoked often depending on the
* refresh interval of the placeholder.
*
* @return the placeholder replacement
* @param argument the optional placeholder argument, null if not specified
* @return the optional placeholder replacement, null to leave the placeholder unreplaced
* @since 1
*/
@Nullable String getReplacement(@Nullable String argument);

14
api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderFactory.java
View File

@ -8,11 +8,25 @@ package me.filoghost.holographicdisplays.api.placeholder;
import org.jetbrains.annotations.Nullable;
/**
* Advanced class to create separate {@link GlobalPlaceholder} instances depending on the placeholder argument, instead
* of providing a single one when registering the placeholder.
* <p>
* This is mostly used for performance reasons, to parse the argument only when necessary, instead of doing it every
* time the method {@link GlobalPlaceholder#getReplacement(String)} is invoked. For example, the argument might consist
* of multiple comma-separated values, be a JSON string, or require a regular expression to parse it.
* <p>
* Another less common use case is to keep a separate internal state for each different argument.
*
* @since 1
*/
public interface GlobalPlaceholderFactory {
/**
* Returns the placeholder instance to provide the replacement for the given argument. This method might be invoked
* again for the same argument if the placeholder is temporarily unused (not displayed to any player).
*
* @param argument the argument for which the placeholder instance will provide the replacement
* @return the placeholder instance
* @since 1
*/
@Nullable GlobalPlaceholder getPlaceholder(@Nullable String argument);

8
api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/GlobalPlaceholderReplaceFunction.java
View File

@ -5,10 +5,14 @@
*/
package me.filoghost.holographicdisplays.api.placeholder;
import me.filoghost.holographicdisplays.api.HolographicDisplaysAPI;
import org.jetbrains.annotations.Nullable;
/**
* Simple callback to provide a placeholder replacement.
* Simplified version of {@link GlobalPlaceholder} where the refresh interval in ticks is passed through the
* registration method
* {@link HolographicDisplaysAPI#registerGlobalPlaceholder(String, int, GlobalPlaceholderReplaceFunction)} as a
* constant.
*
* @since 1
*/
@ -16,7 +20,7 @@ import org.jetbrains.annotations.Nullable;
public interface GlobalPlaceholderReplaceFunction {
/**
* @see GlobalPlaceholder#getReplacement(String)
* Same as {@link GlobalPlaceholder#getReplacement(String)}.
*
* @since 1
*/

15
api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholder.java
View File

@ -10,11 +10,26 @@ import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* An individual placeholder that can display a different text to each player. See {@link Placeholder} for general
* information about placeholders.
*
* @since 1
*/
public interface IndividualPlaceholder extends Placeholder {
/**
* Callback for providing a placeholder replacement for a given player and an optional argument. A different
* replacement can be shown to each player.
* <p>
* The argument is provided through the placeholder text: for example, the argument of {test} is null, the argument
* of {test: hello world} is the string "hello world".
* <p>
* <b>Warning</b>: the implementation should be performance efficient, as it may be invoked often depending on the
* refresh interval of the placeholder and the number of players viewing the hologram.
*
* @param player the player that will see the provided replacement
* @param argument the optional placeholder argument, null if not specified
* @return the optional placeholder replacement, null to leave the placeholder unreplaced
* @since 1
*/
@Nullable String getReplacement(@NotNull Player player, @Nullable String argument);

15
api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderFactory.java
View File

@ -5,14 +5,29 @@
*/
package me.filoghost.holographicdisplays.api.placeholder;
import org.bukkit.entity.Player;
import org.jetbrains.annotations.Nullable;
/**
* Advanced class to create separate {@link IndividualPlaceholder} instances depending on the placeholder argument,
* instead of providing a single one when registering the placeholder.
* <p>
* This is mostly used for performance reasons, to parse the argument only when necessary, instead of doing it every
* time the method {@link IndividualPlaceholder#getReplacement(Player, String)} is invoked. For example, the argument
* might consist of multiple comma-separated values, be a JSON string, or require a regular expression to parse it.
* <p>
* Another less common use case is to keep a separate internal state for each different argument.
*
* @since 1
*/
public interface IndividualPlaceholderFactory {
/**
* Returns the placeholder instance to provide the replacement for the given argument. This method might be invoked
* again for the same argument if the placeholder is temporarily unused (not displayed to any player).
*
* @param argument the argument for which the placeholder instance will provide the replacement
* @return the placeholder instance
* @since 1
*/
@Nullable IndividualPlaceholder getPlaceholder(@Nullable String argument);

8
api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/IndividualPlaceholderReplaceFunction.java
View File

@ -5,18 +5,24 @@
*/
package me.filoghost.holographicdisplays.api.placeholder;
import me.filoghost.holographicdisplays.api.HolographicDisplaysAPI;
import org.bukkit.entity.Player;
import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;
/**
* Simplified version of {@link IndividualPlaceholder} where the refresh interval in ticks is passed through the
* registration method
* {@link HolographicDisplaysAPI#registerIndividualPlaceholder(String, int, IndividualPlaceholderReplaceFunction)} as a
* constant.
*
* @since 1
*/
@FunctionalInterface
public interface IndividualPlaceholderReplaceFunction {
/**
* @see IndividualPlaceholder#getReplacement(Player, String)
* Same as {@link IndividualPlaceholder#getReplacement(Player, String)}.
*
* @since 1
*/

41
api/src/main/java/me/filoghost/holographicdisplays/api/placeholder/Placeholder.java
View File

@ -5,9 +5,50 @@
*/
package me.filoghost.holographicdisplays.api.placeholder;
import me.filoghost.holographicdisplays.api.HolographicDisplaysAPI;
import me.filoghost.holographicdisplays.api.hologram.Hologram;
import me.filoghost.holographicdisplays.api.hologram.PlaceholderSetting;
/**
* A placeholder is a dynamic text value that can be displayed in a text hologram line.
* <p>
* Placeholders can be global (show the same text to all players) or individual (show a different text to each player).
* Global placeholders are preferable when possible, as individual placeholders have a higher performance impact.
* <p>
* To add a placeholder a class must implement either {@link GlobalPlaceholder} or {@link IndividualPlaceholder}, then
* it must be registered with {@link HolographicDisplaysAPI#registerGlobalPlaceholder(String, GlobalPlaceholder)} or
* {@link HolographicDisplaysAPI#registerIndividualPlaceholder(String, IndividualPlaceholder)} by providing an
* identifier string.
* <p>
* The valid formats to display the placeholder inside a text line are:
* <ul>
* <li>{identifier}
* <li>{identifier: argument}
* <li>{plugin/identifier}
* <li>{plugin/identifier: argument}
* </ul>
* <p>
* The parts of the placeholder format are:
* <ul>
* <li>Identifier (required): the identifier used to register the placeholder.
* <li>Argument (optional): the argument passed to the replacement callback.
* <li>Plugin (optional): the name of the plugin to disambiguate if more plugins register the same identifier.
* </ul>
* <p>
* Placeholders are disabled by default and need to be enabled with
* {@link Hologram#setPlaceholderSetting(PlaceholderSetting)}.
*
* @since 1
*/
public interface Placeholder {
/**
* Returns the minimum interval in ticks between invocations of the replacement callback. For individual
* placeholders the interval is counted separately for each player.
* <p>
* Note that more ticks can pass between invocations if no player is near, do not use the replacement callback as a
* timer.
*
* @since 1
*/
int getRefreshIntervalTicks();