Module com.gluonhq.attach.share
Package com.gluonhq.attach.share

Interface ShareService

All Known Implementing Classes:
AndroidShareService, DummyShareService, IOSShareService
public interface ShareService
The ShareService provides a way to share content (text and/or files) from the current app by using other suitable apps existing in the user device.

Example

 ShareService.create().ifPresent(service -> {
      service.share("This is the subject", "This is the content of the message");
  });
When sharing files, the Attach StorageService can be used to create/read the file. Note that on Android, the file has to be located in a public folder (see StorageService#getPublicStorage), or sharing it won't be allowed.

Example

 
 File root = StorageService.create()
           .flatMap(s -> s.getPublicStorage("Documents"))
           .orElseThrow(() -> new RuntimeException("Documents not available"));

 // select or create a file within Documents folder:
 File file = new File(root, "myFile.txt");

 // share the file
 ShareService.create().ifPresent(service -> {
      service.share("text/plain", file);
 });

Requirements

The service requires the following changes on Android and iOS.

However, these are handled automatically by the GluonFX plugin, when used.

Android Configuration

Create the file /src/android/res/xml/file_provider_paths.xml with the following content that allows access to the external storage:

 
    <?xml version="1.0" encoding="utf-8"?>
    <paths>
        <external-path name="external_files" path="." />
    </paths>

And add this provider to the manifest, within the Application tag:

 <manifest package="${application.package.name}"  ...>
   <application ...>
       <provider
           android:name="android.support.v4.content.FileProvider"
           android:authorities="${application.package.name}.fileprovider"
           android:exported="false"
           android:grantUriPermissions="true">
           <meta-data
               android:name="android.support.FILE_PROVIDER_PATHS"
               android:resource="@xml/file_provider_paths" />
       </provider>
   </application>
 </manifest>

iOS Configuration: nothing is required, but if the app is sharing images to the user's local gallery, the key NSPhotoLibraryUsageDescription is required in the app's plist file. Other similar keys could be required as well.

Since:
3.4.0

  • Method Summary

    Modifier and Type
    Method
    Description
    static Optional<ShareService>
    create()
    Returns an instance of ShareService.
    void
    share(String contentText)
    Allows sharing a message, selecting from the suitable apps available in the user device.
    void
    share(String type, File file)
    Allows sharing a file, selecting from the suitable apps available in the user device.
    void
    share(String subject, String contentText)
    Allows sharing a message, selecting from the suitable apps available in the user device.
    void
    share(String subject, String contentText, String type, File file)
    Allows sharing a file, selecting from the suitable apps available in the user device.

  • Method Details

    • create

      static Optional<ShareService> create()
      Returns an instance of ShareService.
      Returns:
      An instance of ShareService.

    • share

      void share(String contentText)
      Allows sharing a message, selecting from the suitable apps available in the user device.
      Parameters:
      contentText - A string with the content to be shared

    • share

      void share(String subject, String contentText)
      Allows sharing a message, selecting from the suitable apps available in the user device. Intended to add a subject to the message, for instance, when it is shared with an email application.
      Parameters:
      subject - A string with the subject of the message
      contentText - A string with the content to be shared

    • share

      void share(String type, File file)
      Allows sharing a file, selecting from the suitable apps available in the user device. Note: On Android, the file has to be located in a public folder (see StorageService#getPublicStorage), or sharing it won't be allowed.
      Parameters:
      type - On Android only, the MIME type of the file. It can be '∗/∗', but not empty. On iOS it can be null. Usual types are:
      • application/xml
      • application/zip
      • application/pdf
      • text/css
      • text/html
      • text/csv
      • text/plain
      • image/png
      • image/jpeg
      • image/gif
      • image/*
      file - A valid file to be shared.

    • share

      void share(String subject, String contentText, String type, File file)
      Allows sharing a file, selecting from the suitable apps available in the user device. A message will be also added. Note: On Android, the file has to be located in a public folder (see StorageService#getPublicStorage), or sharing it won't be allowed.
      Parameters:
      subject - A string with the subject of the message
      contentText - A string with the content to be shared
      type - On Android only, the MIME type of the file. It can be '∗/∗', but not empty. On iOS it can be null. Usual types are:
      • application/xml
      • application/zip
      • application/pdf
      • text/css
      • text/html
      • text/csv
      • text/plain
      • image/png
      • image/jpeg
      • image/gif
      • image/*
      file - A valid file to be shared.