RPUITask
This class is the primary entry point for the presentation of the Research Package framework UI. It presents the steps of an RPOrderedTask (either navigable or just linear) and then provides the RPTaskResult object.
- Inheritance
-
- Object
- DiagnosticableTree
- Widget
- StatefulWidget
- RPUITask
Constructors
RPUITask
- Key? key,
- required RPOrderedTask task,
- Image? carouselBarImage,
- double? carouselBarHorizontalPadding,
- double? carouselBarVerticalPadding,
- Color? carouselBarBackgroundColor,
- RPCarouselBarBuilder? carouselBarBuilder,
- String? nextButtonText,
- ButtonStyle? nextButtonStyle,
- void onSubmit()?,
- void onCancel(
- RPTaskResult? result
Properties
bottomNavigationBuilder
Builds a replacement for the default bottom navigation of the task. When null the default row is shown — a BACK button in a navigable task and a NEXT button, configured through nextButtonText and nextButtonStyle. Those two are ignored when a builder is supplied, since the builder owns the whole row. Return const SizedBox.shrink() to remove the row entirely. The default row hides itself on the steps which carry their own buttons (RPCompletionStep, RPVisualConsentStep and RPConsentReviewStep); the builder is called on every step instead, with RPTaskNavigation.currentStep telling it which one is on screen.
carouselBarBackgroundColor
carouselBarBuilder
Builds a replacement for the default carousel bar at the top of the task. When null the default bar is shown — logo, "x of y" progress and a close button — configured through carouselBarImage, carouselBarHorizontalPadding, carouselBarVerticalPadding and carouselBarBackgroundColor. Those four are ignored when a builder is supplied, since the builder owns the whole bar. Return const SizedBox.shrink() to remove the bar entirely. Note that the default bar holds the only built-in way to cancel a task, so a replacement should provide its own affordance — either blocTask.sendStatus(RPStepStatus.Canceled) to cancel directly, or RPUITaskState.showCancelConfirmationDialog to confirm first.
carouselBarHorizontalPadding
carouselBarImage
carouselBarVerticalPadding
nextButtonStyle
Style for the button that advances to the next step. Properties set here win. Anything left null falls back to the default — a CarpColors.primary background — and then to the ambient ElevatedButtonThemeData, so overriding only shape keeps the default colour. Pass a backgroundColor to change the colour too. The label is drawn white unless a foregroundColor is given here.
nextButtonText
Text for the button that advances to the next step. May be a localization key or a literal — anything the localizations do not recognise is shown as-is. When null the localized 'NEXT' key is used, falling back to "NEXT". Applies to every step; a step's own RPStep.nextButtonText wins over it.
onCancel
The callback function which has to return an RPTaskResult object. This function is called when the participant cancels a survey. The result parameter is optional so if you don't want to do grab the result as part of the callback function you can do so, like the following:
onCancel: ([result]) {
cancelCallBack();
},
It's optional. If not provided (is null) the survey just stops without doing anything with the result.
onSubmit
The callback function which has to return an RPTaskResult object. This function is called when the participant has finished the last step.
task
The task to present. It can be either an RPOrderedTask or an RPNavigableOrderedTask. The RPUITask presents its steps after each other and creates an RPTaskResult object with the same identifier as the task's identifier.
Methods
createState
Creates the mutable state for this widget at a given location in the tree.
Subclasses should override this method to return a newly created instance of their associated State subclass:
@override
State<SomeWidget> createState() => _SomeWidgetState();
The framework can call this method multiple times over the lifetime of a StatefulWidget. For example, if the widget is inserted into the tree in multiple locations, the framework will create a separate State object for each location. Similarly, if the widget is removed from the tree and later inserted into the tree again, the framework will call createState again to create a fresh State object, simplifying the lifecycle of State objects.