Support non-final resource IDs (#29)

Author: MatthiasRobbers

CHANGELOG.md

@@ -1,6 +1,15 @@
 Change Log
 ==========
 
+Version 1.2.0 *(2021-03-14)*
+----------------------------
+* New: Support for non-final resource IDs. See [README.md](https://github.com/MatthiasRobbers/shortbread##non-final-resource-ids)
+for detailed usage instructions.
+* Update: `androidx.annotation:annotation` to `1.1.0`
+* Update: Android Gradle plugin to `4.1.2`
+* Migrated publishing from JCenter to Maven Central
+
+
 Version 1.1.0 *(2020-07-21)*
 -----------------------------
 * New: Support for incremental annotation processing
@@ -13,7 +22,7 @@ Version 1.1.0 *(2020-07-21)*
 
 Version 1.0.2 *(2017-09-24)*
 -----------------------------
-* Fix: Annotated methods are called before `onCreate()` (#13)
+* Fix: Annotated methods are called before `onCreate()` ([#13](https://github.com/MatthiasRobbers/shortbread/issues/13))
 * Update: Support annotations library to `26.0.2`. This requires the new Google Maven Repository:
 
   ```groovy
@@ -29,13 +38,11 @@ Version 1.0.2 *(2017-09-24)*
 
 Version 1.0.1 *(2017-03-04)*
 -----------------------------
-
 * Fix: `Shortbread.create(context)` can now also be called if there are no `@Shortcut` annotations in the code, which before produced a crash. Previously created shortcuts are now removed.
 * Fix: Internal `NullPointerException` when an activity containing method shortcuts is not launched via a method shortcut
 * Add Javadoc for the public API
 
 
-Version 10.2.0 *(2017-02-11)*
+Version 1.0.0 *(2017-02-11)*
 -----------------------------
-
 Initial release

README.md

@@ -9,49 +9,72 @@ you want the shortcut to call.
 
 The four shortcuts above are produced by the following code:
 
-```java
+```kotlin
 @Shortcut(id = "movies", icon = R.drawable.ic_shortcut_movies, shortLabel = "Movies")
-public class MoviesActivity extends Activity {
+class MoviesActivity : Activity() {
 
     // ...
 
     @Shortcut(id = "add_movie", icon = R.drawable.ic_shortcut_add, shortLabel = "Add movie")
-    public void addMovie() {
-        // code to add movie, could show an AddMovieDialogFragment for example
+    fun addMovie() {
+        // could show an AddMovieDialogFragment for example
     }
 }
 ```
 
-```java
+```kotlin
 @Shortcut(id = "books", icon = R.drawable.ic_shortcut_books, shortLabel = "Books")
-public class BooksActivity extends Activity {
+class BooksActivity : Activity() {
 
     // ...
 
     @Shortcut(id = "favorite_books", icon = R.drawable.ic_shortcut_favorite, shortLabel = "Favorite books")
-    public void showFavoriteBooks() {
-        // code to display favorite books, could show a FavoriteBooksFragment for example
+    fun showFavoriteBooks() {
+        // could show a FavoriteBooksFragment for example
     }
 }
 ```
 
 To display the shortcuts, call `Shortbread.create(Context context)` as early as possible in the app, for
 example in `onCreate` of a custom `Application`.
 
-```java
-public class App extends Application {
+```kotlin
+class App : Application() {
 
-    @Override
-    public void onCreate() {
-        super.onCreate();
+    override fun onCreate() {
+        super.onCreate()
 
-        Shortbread.create(this);
+        Shortbread.create(this)
     }
 }
 ```
 
 Shortcuts can be customized with attributes, just like using the framework API.
 
+<details open>
+<summary>Kotlin</summary>
+
+```kotlin
+@Shortcut(
+    id = "books",
+    icon = R.drawable.ic_shortcut_books,
+    shortLabel = "Books",
+    shortLabelRes = R.string.shortcut_books_short_label,
+    longLabel = "List of books",
+    longLabelRes = R.string.shortcut_books_long_label,
+    rank = 2, // order in list, relative to other shortcuts
+    disabledMessage = "No books are available",
+    disabledMessageRes = R.string.shortcut_books_disabled_message,
+    enabled = true, // default
+    backStack = [MainActivity::class, MainActivity::class],
+    activity = MainActivity::class, // the launcher activity to which the shortcut should be attached
+    action = "shortcut_books" // intent action to identify the shortcut from the launched activity
+)
+```
+</details>
+<details>
+<summary>Java</summary>
+
 ```java
 @Shortcut(
     id = "books",
@@ -68,31 +91,83 @@ Shortcuts can be customized with attributes, just like using the framework API.
     activity = MainActivity.class, // the launcher activity to which the shortcut should be attached
     action = "shortcut_books" // intent action to identify the shortcut from the launched activity
 )
-public class BooksActivity extends Activity { /*...*/ }
 ```
+</details>
+
 Download
 --------
 
-### Java
+Shortbread is available on `mavenCentral()`.
+
+<details open>
+<summary>Kotlin</summary>
+
+```groovy
+apply plugin: 'kotlin-kapt'
+
+dependencies {
+    implementation 'com.github.matthiasrobbers:shortbread:1.2.0'
+    kapt 'com.github.matthiasrobbers:shortbread-compiler:1.2.0'
+}
+```
+</details>
+<details>
+<summary>Java</summary>
 
 ```groovy
 dependencies {
-    implementation 'com.github.matthiasrobbers:shortbread:1.1.0'
-    annotationProcessor 'com.github.matthiasrobbers:shortbread-compiler:1.1.0'
+    implementation 'com.github.matthiasrobbers:shortbread:1.2.0'
+    annotationProcessor 'com.github.matthiasrobbers:shortbread-compiler:1.2.0'
 }
 ```
+</details>
 
-### Kotlin
+Non-final resource IDs
+----------------------
+If you are using resource IDs in `@Shortcut` attributes auch as `shortLabelRes`, which is recommended, you may see this
+warning in Android Studio:
+> Resource IDs will be non-final in Android Gradle Plugin version 5.0, avoid using them as annotation attributes.
 
-```groovy
-apply plugin: 'kotlin-kapt'
+If the annotation is located inside a library, the project won't even compile. To overcome this, add the Shortbread
+Gradle plugin and apply it to your modules:
 
-dependencies {
-    implementation 'com.github.matthiasrobbers:shortbread:1.1.0'
-    kapt 'com.github.matthiasrobbers:shortbread-compiler:1.1.0'
+```groovy
+buildscript {
+    repositories {
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.github.matthiasrobbers:shortbread-gradle-plugin:1.2.0'
+    }
 }
 ```
 
+```groovy
+apply plugin: 'com.github.matthiasrobbers.shortbread'
+```
+
+Now make sure you use `R2` instead of `R` inside all `@Shortcut` annotations. If you are using `mipmap` as shortcut icon
+resource type, switch to `drawable` by simply moving the resources from the `mipmap-` folders to the corresponding
+`drawable-` folders.
+
+```kotlin
+@Shortcut(icon = R2.drawable.ic_shortcut_movies, shortLabelRes = R2.string.label_movies)
+```
+
+The plugin uses the [Butter Knife][2] Gradle plugin to generate the `R2` class with final values. Referencing them does
+not make the warning disappear (you can suppress it with `@SuppressLint("NonConstantResourceId")`), but most likely will
+be the only way to use resource IDs in annotations in the future.
+<details>
+<summary>Alternative to Gradle plugin</summary>
+
+If for you can't (or don't want to) use the plugin, you can use the additional deprecated string attributes like
+`iconResName`, `shortLabelResName` and so on.
+
+```kotlin
+@Shortcut(iconResName = "ic_shortcut_movies", shortLabelResName = "label_movies")
+```
+</details>
+
 License
 -------
 
@@ -113,3 +188,4 @@ License
 
 
  [1]: https://developer.android.com/guide/topics/ui/shortcuts.html
+ [2]: https://github.com/JakeWharton/butterknife

build.gradle

@@ -1,12 +1,14 @@
+apply plugin: "com.github.ben-manes.versions"
+
 buildscript {
     repositories {
         jcenter()
         google()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:3.6.4'
-        classpath 'com.vanniktech:gradle-maven-publish-plugin:0.12.0'
-        classpath 'com.jfrog.bintray.gradle:gradle-bintray-plugin:1.8.5'
+        classpath 'com.android.tools.build:gradle:4.1.2'
+        classpath 'com.github.ben-manes:gradle-versions-plugin:0.36.0'
+        classpath 'com.vanniktech:gradle-maven-publish-plugin:0.14.2'
     }
 }
 
@@ -18,12 +20,11 @@ subprojects {
 }
 
 ext {
-    compileSdkVersion = 29
-    buildToolsVersion = '29.0.3'
+    compileSdkVersion = 30
+    buildToolsVersion = '30.0.3'
     minSdkVersion = 14
     sourceCompatibilityVersion = JavaVersion.VERSION_1_8
     targetCompatibilityVersion = JavaVersion.VERSION_1_8
-    androidxAnnotationVersion = '1.1.0'
     autoServiceVersion = '1.0-rc7'
     incapVersion = '0.3'
 }

gradle.properties

@@ -2,7 +2,7 @@ org.gradle.jvmargs=-Xmx1536m
 android.useAndroidX=true
 
 GROUP=com.github.matthiasrobbers
-VERSION_NAME=1.1.0
+VERSION_NAME=1.2.0
 
 POM_URL=https://github.com/matthiasrobbers/shortbread
 POM_SCM_URL=https://github.com/matthiasrobbers/shortbread
@@ -16,5 +16,3 @@ POM_LICENCE_DIST=repo
 POM_DEVELOPER_ID=matthiasrobbers
 POM_DEVELOPER_NAME=Matthias Robbers
 POM_DEVELOPER_URL=https://github.com/matthiasrobbers/
-
-RELEASE_SIGNING_ENABLED=false

gradle/wrapper/gradle-wrapper.properties

@@ -3,4 +3,4 @@ distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
 zipStoreBase=GRADLE_USER_HOME
 zipStorePath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-5.6.4-all.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-6.8.3-all.zip

publish.gradle

@@ -1,4 +1,17 @@
+buildscript {
+    repositories {
+        mavenCentral()
+        google()
+        mavenLocal()
+    }
+
+    dependencies {
+        classpath "com.github.matthiasrobbers:shortbread-gradle-plugin:${VERSION_NAME}"
+    }
+}
+
 apply plugin: 'com.android.application'
+apply plugin: 'com.github.matthiasrobbers.shortbread'
 
 android {
     compileSdkVersion project.compileSdkVersion
@@ -7,7 +20,7 @@ android {
     defaultConfig {
         applicationId "com.example.shortbread"
         minSdkVersion project.minSdkVersion
-        targetSdkVersion 29
+        targetSdkVersion 30
         versionCode 1
         versionName "1.0"
     }

sample/build.gradle

@@ -5,10 +5,11 @@
 import android.widget.TextView;
 
 import com.example.shortbread.R;
+import com.example.shortbread.R2;
 
 import shortbread.Shortcut;
 
-@Shortcut(id = "books", icon = R.drawable.ic_shortcut_books, shortLabelRes = R.string.label_books, rank = 1)
+@Shortcut(id = "books", icon = R2.drawable.ic_shortcut_books, shortLabelRes = R2.string.label_books, rank = 1)
 public class BooksActivity extends Activity {
 
     @Override
@@ -17,8 +18,8 @@ protected void onCreate(Bundle savedInstanceState) {
         setContentView(R.layout.activity_books);
     }
 
-    @Shortcut(id = "favorite_books", icon = R.drawable.ic_shortcut_favorite, shortLabel = "Favorite books", rank = 2,
-            disabledMessage = "You have no favorite books")
+    @Shortcut(id = "favorite_books", icon = R2.drawable.ic_shortcut_favorite, shortLabelRes = R2.string.label_books_method,
+            rank = 2, disabledMessage = "You have no favorite books")
     public void showFavoriteBooks() {
         ((TextView) findViewById(R.id.text)).setText("Favorite books");
     }

sample/proguard-rules.pro

@@ -6,11 +6,12 @@
 
 import com.example.shortbread.MainActivity;
 import com.example.shortbread.R;
+import com.example.shortbread.R2;
 import com.example.shortbread.books.BooksActivity;
 
 import shortbread.Shortcut;
 
-@Shortcut(id = "movies", action = "movie_shortcut", icon = R.drawable.ic_shortcut_movies, rank = 3,
+@Shortcut(id = "movies", action = "movie_shortcut", icon = R2.drawable.ic_shortcut_movies, rank = 3,
         backStack = {MainActivity.class, BooksActivity.class})
 public class MoviesActivity extends Activity {
 
@@ -20,7 +21,7 @@ protected void onCreate(Bundle savedInstanceState) {
         setContentView(R.layout.activity_movies);
     }
 
-    @Shortcut(id = "add_movie", icon = R.drawable.ic_shortcut_add, shortLabel = "Add movie", rank = 4)
+    @Shortcut(id = "add_movie", icon = R2.drawable.ic_shortcut_add, shortLabelRes = R2.string.label_movies_method, rank = 4)
     public void addMovie() {
         ((TextView) findViewById(R.id.text)).setText("Add movie");
     }