ginivision/net.gini.android.vision.onboarding

Package net.gini.android.vision.onboarding

Contains the Activity and Fragments used for the Onboarding Screen.

Screen API

The net.gini.android.vision.onboarding.OnboardingActivity is launched directly by the net.gini.android.vision.camera.CameraActivity. It can be configured by overriding Gini Vision Library app resources and/or by supplying the net.gini.android.vision.camera.CameraActivity with an java.util.ArrayList of net.gini.android.vision.onboarding.OnboardingPage objects in the net.gini.android.vision.camera.CameraActivity.EXTRA_IN_ONBOARDING_PAGES extra.

Component API

To use the Component API you have to include the net.gini.android.vision.onboarding.OnboardingFragmentStandard or the net.gini.android.vision.onboarding.OnboardingFragmentCompat in an Activity in your app (a dedicated Activity is recommended). To receive events from the Fragments your Activity must implement the net.gini.android.vision.onboarding.OnboardingFragmentListener interface.

The Onboarding Screen was designed as a semi-transparent overlay for the camera preview. Your Activity should be configured to be transparent and the Camera Fragment should not stop the camera when the onboarding is shown.

Types

ConditionalPages

androidJvm

Internal use only.

public enum ConditionalPages

DefaultPagesPhone

androidJvm

Internal use only.

public enum DefaultPagesPhone

DefaultPagesTablet

androidJvm

Internal use only.

public enum DefaultPagesTablet

OnboardingActivity

androidJvm

Screen API

When you use the Screen API, the {@code OnboardingActivity} displays important advice for correctly photographing a document.

The {@code OnboardingActivity} is started by the CameraActivity when the latter is launched for the first time. You may disable this behavior - we highly recommend keeping it - by passing {@code false} to setShouldShowOnboardingAtFirstRun when creating a GiniVision instance. If you don't use GiniVision yet you can also use the extra EXTRA_IN_SHOW_ONBOARDING_AT_FIRST_RUN with {@code false} when starting the CameraActivity .

You can change the number of displayed pages and their content (image and short text) by setting an {@code ArrayList} containing OnboardingPage objects when building a instance with . If you don't use GiniVision yet you can also provide the list using the extra for the Screen API and or for the Component API.

Customizing the Onboarding Screen

Customizing the look of the Onboarding Screen is done via overriding of app resources or by providing your own pages with your own strings and drawable resources.

The following items are customizable:

Next button icon: via images for mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi named {@code * gv_onboarding_fab_next.png}
Next button color: via the color resources named {@code gv_onboarding_fab} and {@code * gv_onboarding_fab_pressed}
Page indicators: via images for mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi named {@code * gv_onboarding_indicator_active.png} and {@code gv_onboarding_indicator_inactive.png}
Onboarding message color: via the color resource named {@code gv_onboarding_message}
Onboarding message font: via overriding the style named {@code * GiniVisionTheme.Onboarding.Message.TextStyle} and setting an item named {@code gvCustomFont} with the path to the font file in your {@code assets} folder
Onboarding message text style: via overriding the style named {@code * GiniVisionTheme.Onboarding.Message.TextStyle} and setting an item named {@code android:textStyle} to {@code normal} , {@code bold} or {@code italic}
Onboarding message text size: via overriding the style named {@code * GiniVisionTheme.Onboarding.Message.TextStyle} and setting an item named {@code android:textSize} to the desired {@code sp} size
Tablet Onboarding Pages:
- First page image via images for sw600dp-mdpi, sw600dp-hdpi, sw600dp-xhdpi, sw600dp-xxhdpi, sw600dp-xxxhdpi named {@code gv_onboarding_lighting.png}
- First page text: via the string resource named {@code gv_onboarding_ligthing}
- Second page image via images for sw600dp-mdpi, sw600dp-hdpi, sw600dp-xhdpi, sw600dp-xxhdpi, sw600dp-xxxhdpi named {@code gv_onboarding_flat.png}
- Second page text: via the string resource named {@code gv_onboarding_flat}
- Third page image: via images for sw600dp-mdpi, sw600dp-hdpi, sw600dp-xhdpi, sw600dp-xxhdpi, sw600dp-xxxhdpi named {@code gv_onboarding_parallel.png}
- Third page text: via the string resource named {@code gv_onboarding_parallel}
- Fourth page image: via images for sw600dp-mdpi, sw600dp-hdpi, sw600dp-xhdpi, sw600dp-xxhdpi, sw600dp-xxxhdpi named {@code gv_onboarding_align.png}
- Fourth page text: via the string resource named {@code gv_onboarding_align}
Phone Onboarding Pages:
- First page image: via images for mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi named {@code * gv_onboarding_flat.png}
- First page text: via the string resource named {@code gv_onboarding_flat}
- Second page image: via images for mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi named {@code * gv_onboarding_parallel.png}
- Second page text: via the string resource named {@code gv_onboarding_parallel}
- Third page image: via images for mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi named {@code * gv_onboarding_align.png}
- Third page text: via the string resource named {@code gv_onboarding_align}
Background transparency: via the string resource named {@code * gv_onboarding_page_fragment_background_alpha} which must contain a real number between [0,1].
Background color: via the color resource named {@code gv_background} . Note: this color resource is global to all Activities ( CameraActivity , , ReviewActivity , AnalysisActivity )

Important: All overriden styles must have their respective {@code Root.} prefixed style as their parent. Ex.: the parent of {@code GiniVisionTheme.Onboarding.Message.TextStyle} must be {@code Root.GiniVisionTheme.Onboarding.Message.TextStyle} .

Customizing the Action Bar

Customizing the Action Bar is also done via overriding of app resources and each one - except the title string resource - is global to all Activities ( CameraActivity , , ReviewActivity , AnalysisActivity ).

The following items are customizable:

Background color: via the color resource named {@code gv_action_bar} (highly recommended for Android 5+: customize the status bar color via {@code gv_status_bar} )
Title: via the string resource named {@code gv_title_onboarding}
Title color: via the color resource named {@code gv_action_bar_title}
Back button: via images for mdpi, hdpi, xhdpi, xxhdpi, xxxhdpi named {@code gv_action_bar_back}

public class OnboardingActivity extends AppCompatActivity implements OnboardingFragmentListener

OnboardingFragmentCompat

androidJvm

Component API

When you use the Component API with the Android Support Library, the {@code * OnboardingFragmentCompat} displays important advice for correctly photographing a document.

Note: Your Activity hosting this Fragment must extend the and use an AppCompat Theme.

Include the {@code OnboardingFragmentCompat} into your layout either directly with {@code * } in your Activity's layout or using the androidx.fragment.app.FragmentManager .

The default way of showing the Onboarding Screen is as an overlay above the camera preview with a semi-transparent background.

By default an empty last page is added to enable the revealing of the camera preview before the Onboarding Screen is dismissed.

If you would like to display a different number of pages, you can use the or factory method and provide a list of OnboardingPage objects.

If you would like to disable the appending of the empty last page, you can use the or the factory method.

An OnboardingFragmentListener instance must be available until the {@code * OnboardingFragmentCompat} is attached to an activity. Failing to do so will throw an exception. The listener instance can be provided either implicitly by making the hosting Activity implement the OnboardingFragmentListener interface or explicitly by setting the listener using setListener .

Your Activity is automatically set as the listener in onCreate .

Customizing the Onboarding Screen

See the OnboardingActivity for details.

public class OnboardingFragmentCompat extends Fragment implements OnboardingFragmentImplCallback, OnboardingFragmentInterface

OnboardingFragmentHelper

androidJvm

final class OnboardingFragmentHelper

OnboardingFragmentImpl

androidJvm

class OnboardingFragmentImpl extends OnboardingScreenContract.View

OnboardingFragmentImplCallback

androidJvm

Internal use only.

public interface OnboardingFragmentImplCallback implements FragmentImplCallback

OnboardingFragmentInterface

androidJvm

Methods which both Onboarding Fragments must implement.

public interface OnboardingFragmentInterface

OnboardingFragmentListener

androidJvm

Interface used by OnboardingFragmentStandard and OnboardingFragmentCompat to dispatch events to the hosting Activity.

public interface OnboardingFragmentListener

OnboardingFragmentStandard

androidJvm

Component API

When you use the Component API without the Android Support Library, the {@code OnboardingFragmentStandard} displays important advice for correctly photographing a document.

Include the {@code OnboardingFragmentStandard} into your layout either directly with {@code } in your Activity's layout or using the android.app.FragmentManager .

The default way of showing the Onboarding Screen is as an overlay above the camera preview with a semi-transparent background.

By default an empty last page is added to enable the revealing of the camera preview before the Onboarding Screen is dismissed.

If you would like to display a different number of pages, you can use the or factory method and provide a list of OnboardingPage objects.

If you would like to disable the appending of the empty last page, you can use the or the createInstanceWithoutEmptyLastPage factory method.

An OnboardingFragmentListener instance must be available until the {@code OnboardingFragmentStandard} is attached to an activity. Failing to do so will throw an exception. The listener instance can be provided either implicitly by making the hosting Activity implement the OnboardingFragmentListener interface or explicitly by setting the listener using setListener .

Your Activity is automatically set as the listener in onCreate .

Customizing the Onboarding Screen

See the OnboardingActivity for details.

public class OnboardingFragmentStandard extends Fragment implements OnboardingFragmentImplCallback, OnboardingFragmentInterface

OnboardingPage

androidJvm

The {@code OnboardingPage} is used by the Onboarding Fragment to display an image and a short text.

Use this class to show a different number of pages in the Onboarding Screen. Customizing the default onboarding pages can be done via overriding of app resources.

When using the Screen API set an java.util.ArrayList containing {@code OnboardingPage} objects as the EXTRA_IN_ONBOARDING_PAGES when starting the CameraActivity .

When using the Componenent API provide an java.util.ArrayList containing {@code OnboardingPage} objects as the argument for the Onboarding Fragment factory method or .

public class OnboardingPage implements Parcelable