Package net.dv8tion.jda.api.components.mediagallery

Interface MediaGalleryItem

All Superinterfaces:
SerializableData
All Known Implementing Classes:
MediaGalleryItemFileUpload, MediaGalleryItemImpl
public interface MediaGalleryItem extends SerializableData
A singular item (not a component) of a MediaGallery, you can mark it as a spoiler and set a description.

  • Field Details

    • MAX_DESCRIPTION_LENGTH

      static final int MAX_DESCRIPTION_LENGTH
      The maximum number of characters an item's description can have. (1024)
      See Also:

  • Method Details

    • fromUrl

      @Nonnull static MediaGalleryItem fromUrl(@Nonnull String url)
      Constructs a new MediaGalleryItem from the given URL.

      Re-uploading external images

      If you instead want to re-upload the content of the URL, you have two options to reference images to upload:
      1. Use fromFile(FileUpload) instead, it will set a URI similar to attachment://file.ext, and automatically adds the attachment to the request.
        This is the easiest, but it may upload unnecessary files when editing, as it is not aware if the file already exists on the message, wasting bandwidth and potentially slowing down response times.
      2. Do the same manually, meaning you need to pass the attachment://file.ext URI, where file.ext is the name of the file you will upload, then, on the request, add the file, using MessageCreateRequest#addFiles(FileUpload...) for example.
        This is more tedious but gives you full control over the uploads.

      Example 

      
 MessageChannel channel; // = reference of a MessageChannel
 MediaGalleryItem item = MediaGalleryItem.fromUrl("attachment://cat.png") // we specify this in sendFile as "cat.png"
     .setDescription("This is a cute car :3");
 MediaGallery gallery = MediaGallery.of(item);
 // It's recommended to use a more robust HTTP library instead,
 // such as Java 11+'s HttpClient, or OkHttp (included with JDA), among many other options.
 InputStream file = new URL("https://http.cat/500").openStream();
 channel.sendFiles(FileUpload.fromData(file, "cat.png"))
     .setComponents(gallery)
     .useComponentsV2()
     .queue();
      Parameters:
      url - The URL of the item to display
      Returns:
      The new MediaGalleryItem
      Throws:
      IllegalArgumentException - If null is provided

    • fromFile

      @Nonnull static MediaGalleryItem fromFile(@Nonnull FileUpload file)
      Constructs a new MediaGalleryItem from the FileUpload.

      This method can also be used to upload external resources, such as by using FileUpload.fromData(InputStream, String), in which case it will re-upload the entire file.

      This will automatically add the file when building the message, as such you do not need to add it manually (with MessageCreateRequest.addFiles(FileUpload...) for example).

      Example 

      
 MessageChannel channel; // = reference of a MessageChannel
 // It's recommended to use a more robust HTTP library instead,
 // such as Java 11+'s HttpClient, or OkHttp (included with JDA), among many other options.
 InputStream file = new URL("https://http.cat/500").openStream();
 // You can also replace this with a local file
 MediaGalleryItem item = MediaGalleryItem.fromFile(FileUpload.fromData(file, "cat.png"))
     .setDescription("This is a cute car :3");
 MediaGallery mediaGallery = MediaGallery.of(item);
 channel.sendComponents(section)
     .useComponentsV2()
     .queue();
      Parameters:
      file - The FileUpload to display
      Returns:
      The new MediaGalleryItem
      Throws:
      IllegalArgumentException - If null is provided

    • withDescription

      @Nonnull @CheckReturnValue MediaGalleryItem withDescription(@Nullable String description)
      Creates a new MediaGalleryItem with the provided description.
      The description is known as an "alternative text", and must not exceed 1024 characters.
      Parameters:
      description - The new description
      Returns:
      The new MediaGalleryItem
      Throws:
      IllegalArgumentException - If the description is longer than 1024 characters.

    • withSpoiler

      @Nonnull @CheckReturnValue MediaGalleryItem withSpoiler(boolean spoiler)
      Creates a new MediaGalleryItem with the provided spoiler status.
      Spoilers are hidden until the user clicks on it.
      Parameters:
      spoiler - The new spoiler status
      Returns:
      The new MediaGalleryItem

    • getUrl

      @Nonnull String getUrl()
      The URL of this item, this is always where the file originally came from.
      This can be either attachment://filename.extension or an actual URL.

      If you want to download the file, you should use getResolvedMedia() then ResolvedMedia.getProxy(), to avoid connecting your bot to unknown servers.

      Returns:
      The URL of this item

    • getResolvedMedia

      @Nullable ResolvedMedia getResolvedMedia()
      The media resolved from this item, this is only available if you receive this component from Discord.
      Returns:
      Possibly-null ResolvedMedia

    • getDescription

      @Nullable String getDescription()
      The description of this item, or null if none has been set.
      Returns:
      Possibly-null description

    • isSpoiler

      boolean isSpoiler()
      Whether this item is hidden until the user clicks on it.
      Returns:
      true if this is hidden by default, false otherwise