mydomain
No ADS
No ADS

FlutterArtist Code Flow Viewer

  1. Code Flow Viewer
  2. ExecutionTrace(s)
  3. ExecutionTrace(Startup)
  4. ExecutionTrace(NaturalLoad)
  5. ExcutionTrace(UserMethodCall)
  6. ExcutionTrace(LibMethodCall)
  7. ExecutionTrace(TaskUnit)
  8. ExecutionTrace(IncomingEvents)
Debug Code Flow Viewer is one of the most critical and unique debugging features of FlutterArtist. This tool is designed with two primary objectives:
  • For Platform Developers: Helps observe the "flow" of source code in detail. With the Line-Code-Id identification system (e.g., #11111, #22222), you can instantly trace the exact location of the executed line of code within tens of thousands of platform code lines.
  • For the Application Developer: It provides a visual insight into how FlutterArtist operates under the hood, helping you understand the data processing logic without getting lost in traditional Logs.

1. Code Flow Viewer

FlutterArtist's strength lies in its sequential execution of TaskUnit(s) placed in an Execution Queue. During execution, a TaskUnit can generate subsequent TaskUnit(s) and add them to the queue. This process continues until the queue is completely empty.
Let’s examine what happens when you open the Currency01a example in the FlutterArtist Demo app:
No ADS
On the Currency01a screen, the appearance of special UI components (known as ContextProviderView(s)) such as BlockItemsView, BlockItemDetailView, BlockSectionView, and BlockControlBar triggers the "Natural Load" mechanism.
  • Context Identification: FlutterArtist identifies that these views are associated with the Currency01aBlock of the Currency01aShelf.
  • TaskUnit Initialization: A _BlockQueryTaskUnit is created to handle the data query for this Block and is placed in the queue. (All the aforementioned views, capable of providing a Block-context, have triggered this mechanism).
  • Data Processing: _BlockQueryTaskUnit executes and returns a list of CurrencyInfo(s).
  • Since the BlockItemDetailView (which provides an Item-context) is visible and the CurrencyInfo(s) list is not empty, a _BlockSetItemAsCurrentTaskUnit is created. This task determines the current item, loads the detailed data (CurrencyData).
Once all TaskUnits are completed (the queue is empty), the screen will be fully Refreshed with the data ready for display.
Please note that the above process has been explained in the simplest way possible; it's actually a bit more complex. If you're interested, you can refer to the articles below for more information:
  • FlutterArtist Natural Load example 1 (***)
  • FlutterArtist Queue (***)
FlutterArtist.navigatorObserver
FlutterArtist uses FlutterArtist.navigatorObserver as a RouteObserver to monitor which ContextProviderViews are entering or leaving the screen. From there, it identifies the relevant Block(s) or Scalar(s) and the data contexts they provide. To enable this mechanism, you must register the RouteObserver in your MaterialApp:
main.dart (*)
GetMaterialApp(
  title: 'Flutter Artist Demo',
  debugShowCheckedModeBanner: false,
  scrollBehavior: const MaterialScrollBehavior().copyWith(
    dragDevices: {PointerDeviceKind.mouse, PointerDeviceKind.touch},
  ),
  navigatorObservers: [FlutterArtist.navigatorObserver], // <---
  ...
)
  • FlutterArtist Starter (***)

2. ExecutionTrace(s)

An ExecutionTrace is a ListItem displayed on the left panel of the CodeFlowViewerDialog. Each ExecutionTrace acts as a container, comprising multiple detailed TraceStep(s) that occur within that specific flow.
codeFlowRetentionPeriodInSeconds
By default, ExecutionTraces are retained in the list for at least 20 seconds until new ones are added. When new execution traces appear, the system automatically discards elements older than this timeframe; otherwise, they remain available for debugging. You can configure this value via the FlutterArtist.config() method:
main.dart (*)
await FlutterArtist.config( 
  ...
  codeFlowRetentionPeriodInSeconds: 20,
  ...
);
No ADS

3. ExecutionTrace(Startup)

ExecutionTrace("Startup") logs every event that occurs as soon as the user accesses the app. At this stage, a series of critical background processes are executed:
Configuration Initialization
Logs the FlutterArtist.config() call. After this step, your app's structure is fully defined and viewable via the Debug Storage Viewer.
Auto-Authentication
Reads locally stored login info (Username, AccessToken,...), allowing users to bypass re-authentication.
Data Sync & Personalization
Fetches GlobalData from the server and applies the user's preferred Locale and Theme settings from previous sessions.
In particular, ExecutionTrace("Startup") performs rigorous validation of all Shelves in the StorageStructure to ensure system integrity. If any errors are detected, the app will immediately trigger a "Red Screen" and fail to start. Validation items include:
Valid Identifiers
Ensuring valid names for Block(s), Scalar(s), and FilterModel(s).
Correct Referencing
Ensuring Block(s) and Scalar(s) point to a FilterModel that actually exists within the Shelf.
Generics Consistency
Ensuring that Generics parameters across related FilterModel, Block, and FormModel match perfectly.
Property Constraints
Ensuring that names for FormProp(s), FilterCriterion(s), and TildeFilterCriterion(s) are valid and unique.
Configuration Error Examples
Below are a few examples of error messages you might encounter when the app fails to start due to misconfiguration. These messages help you pinpoint exactly where the error lies within your Shelf architecture.
Invalid FILTER_CRITERIA parameter type on a Scalar
  • This error occurs when a Scalar without a FILTER_MODEL is defined with a FilterCriteria type other than EmptyFilterCriteria.
Filter-Criteria of 'SystemReportScalar' scalar must be 'EmptyFilterCriteria' because this scalar does not have a FILTER_MODEL.
>> Currently, SystemReportScalar<FILTER_CRITERIA> = SystemReportFilterCriteria
Duplicate Block name within the same Shelf
  • Each Block within a Shelf must have a unique identifier (name). If you accidentally duplicate a name, the system will alert you immediately.
Duplicate block 'category-block' in 'CatProductShelf'
Double-check CatProductShelf.defineShelfStructure() method.
Invalid FilterCriterion name
  • The system validates identifier strings (e.g., checking for trailing spaces or special characters) to ensure subsequent queries do not suffer from logic errors.
Invalid criterionBaseName 'email '.
@see the 'SupplierFilterModel.defineFilterModelStructure()' method for details.

4. ExecutionTrace(NaturalLoad)

"Natural Load" has been explained at the top of the article.

5. ExcutionTrace(UserMethodCall)

The ExecutionTrace(UserMethodCall) is created when you call the FlutterArtist.codeFlowLogger.addMethodCall() method; it tells you the physical location of the method surrounding this call.
ExampleBox._showExample()
class ExampleBox extends StatelessWidget {
  ...
  void _showExample() {
    FlutterArtist.codeFlowLogger.addMethodCall(
      ownerClassInstance: this,
      currentStackTrace: StackTrace.current,
      parameters: {},
    );
    // Other code... 
  }
  ...
}
If you have a method that initiates a critical business logic or action—for instance, when a user clicks a button to retrieve a system report — you should place the FlutterArtist.codeFlowLogger.addMethodCall() call at the very first line of your method.
Identify the Entry Point
In a queue-based system like FlutterArtist, a single user action can trigger a series of background tasks. Marking the starting point helps you identify exactly "who" sparked that chain of events.
Instant Source Navigation
Thanks to the magic of StackTrace.current, you don't have to search through hundreds of files. Simply click the ExecutionTrace in the Debug UI, and you'll be directed to the exact file and line where the action began.
Trace Input Parameters
You can log the state of parameters at the moment the function is called. This is incredibly useful for verifying whether a logic error stems from the algorithm or from "skewed" input data.

6. ExcutionTrace(LibMethodCall)

Several core and critical methods of FlutterArtist are pre-integrated with the FlutterArtist.codeFlowLogger.addMethodCall() call at their very first line. This generates ExecutionTrace(LibMethodCall), which you can observe directly on the Debug Code Flow Viewer.
ExecutionTrace(LibMethodCall) uses a "call" icon (Icons.call) in black, as opposed to the blue color used for UserMethodCall. This color distinction helps you quickly separate application logic from the library's internal logic.

7. ExecutionTrace(TaskUnit)

ExecutionTrace(TaskUnit) records the detailed steps within the execution lifecycle of a TaskUnit. Within the FlutterArtist ecosystem, there are numerous specialized TaskUnit types handling various roles:
  • blockQuery (_BlockQueryTaskUnit)
  • blockSetItemAsCurrent (_BlockSetItemAsCurrentTaskUnit)
  • formModelLoadData (_FormModelLoadDataTaskUnit)
  • formModelSaveForm (_FormModelSaveFormTaskUnit)
  • ...
During execution, a TaskUnit may spawn secondary TaskUnits and place them in the queue. However, on the Debug Code Flow Viewer interface, ExecutionTrace(TaskUnit) will not be displayed as nested. They are arranged flat on the left-side list in chronological order of creation, allowing you to clearly follow the system's timeline.

8. ExecutionTrace(IncomingEvents)

When a user performs CRUD (Create, Update, Delete) operations on an item within a block, an event is emitted to notify the relevant Shelf(s). These events can be actively deferred, but as soon as they are sent, an ExecutionTrace(IncomingEvents) is created to record the entire "handover" process.
The event log includes:
  • Determines the type of events sent, for example: [Event(SupplierInfo), Event(ProductInfo)].
  • Specifies which Shelf(s), Block(s), or Scalar(s) are receiving the notifications.
Logs the current state of the objects (e.g., whether they are currently visible on the screen) and their reactions: creating a TaskUnit to re-query, or simply marking the required reaction and switching to a "pending" state.
No ADS

FlutterArtist

Show More
No ADS

FlutterArtist

Show More
No ADS
No ADS

Newest Articles

Show More
No ADS