Spectrum

A fast UI hierarchy inspector for Android applications.

Why do you need it

We all love to write code. I'm sure we know every class, every method, every variable that we have ever created or edited. Man's code is his castle. But one day we have to go to another castle. And what will we see there? At first glance, this is all the same familiar code. All the same Activities, Fragments and what else is there in the Android. But the application is large and it will take a lot of time to study its structure.

And here Spectrum comes to the rescue. This utility will monitor changes in the application and print actual Activity-Fragment-View connections tree to the logcat. Now, it will take much less time to find the class in which you need to correct TextView text color from the bug report screenshot.

How to use

To enable Spectrum just add this line into onCreate method of your activity:

public void onCreate(Bundle savedInstanceState) {
    Spectrum.explore(this);
    // your perfect code
}

Or if you want to inspect all activities add this line into onCreate method of your Application class:

public void onCreate() {
    Spectrum.explore(this);
    // your perfect code again
}

Important: If you imported Spectrum as gradle dependency the code above is redundant. By default Spectrum is initializing automatically through content provider. You can set boolean resource spectrum_auto_init to false if you want to disable this behavior.

Now you will see something like this in IDE logcat:

To start building a report manually call static method report:

// moment to build new Spectrum report
public void onBuildNewReport() {
    Spectrum.report();
}

How to integrate

You can add source file Spectrum.java to your project sources if you want to test the library or if you need to use it once. This file contains all the basic functionality of the utility.

In order to use the library to its fullest, add new gradle dependency:

implementation 'com.acelost.spectrum:spectrum:0.0.4'

How to configure

You can configure Spectrum output programmatically via configurator:

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        Spectrum.configure()
                .logTag("MyCustomTag")
                .showViewHierarchy(false)
                .sampleReporting(false);
        Spectrum.explore(this);
    }
}

Or you can apply configuration via resources:

// values/spectrum_config.xml
<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="spectrum_log_tag">MyCustomTag</string>
    <bool name="spectrum_show_view_hierarchy">false</bool>
    <bool name="spectrum_sample_reporting">false</bool>
</resources>

Complete list of configuration options:

Log tag - log tag you want to use for output:
- java: logTag(String tag);
- xml: <string name="spectrum_log_tag">...</string>
- default: "Spectrum"
Log level - log level you want to use for output (see valid values in android.util.Log class):
- java: logLevel(int level);
- xml: <integer name="spectrum_log_level">...</integer>
- default: Log.DEBUG // 3
Show view hierarchy - whether to display view hierarchy or not:
- java: showViewHierarchy(boolean show);
- xml: <bool name="spectrum_show_view_hierarchy">...</bool>
- default: True
Append packages - whether to append package to class name or not:
- java: showViewHierarchy(boolean show);
- xml: <bool name="spectrum_append_packages">...</bool>
- default: False
Append view id - whether to append id to View nodes in hierarchy or not:
- java: appendViewId(boolean append);
- xml: <bool name="spectrum_append_view_id">...</bool>
- default: True
Append view location - whether to append location on screen to View nodes in hierarchy or not:
- java: appendViewLocation(boolean append);
- xml: <bool name="spectrum_append_view_location">...</bool>
- default: False
Auto reporting - whether to trigger building report automatically after any changes:
- java: autoReporting(boolean enable);
- xml: <bool name="spectrum_auto_reporting">...</bool>
- default: True
Gesture reporting - whether to trigger building report when user double taps:
- java: gestureReporting(boolean enable);
- xml: <bool name="spectrum_gesture_reporting">...</bool>
- default: True
Sample reporting - whether to sample reporting or build new report after any changes:
- java: sampleReporting(boolean sample);
- xml: <bool name="spectrum_sample_reporting">...</bool>
- default: True

Also you can set custom inspectors for certain types of view:

public class MyApplication extends Application {
    @Override
    public void onCreate() {
        Spectrum.register(
                new Spectrum.ViewInspector() {
                    @Override
                    public boolean canInspect(@NonNull View view) {
                        return view instanceof SwitchCompat;
                    }

                    @Override
                    public void inspect(@NonNull View view, @NonNull Spectrum.OutputBuilder output) {
                        if (view instanceof SwitchCompat) {
                            final SwitchCompat switchCompat = (SwitchCompat) view;
                            if (switchCompat.isChecked()) {
                                output.append(" [checked]");
                            }
                        }
                    }
                }
        );
    }
}

F.A.Q.

TODO

Do you still have questions? Ask them in Telegram group t.me/spectrum_android.

License

Copyright 2019 The Spectrum Author

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

acelost / Spectrum