Writing a file browser in MadButterfly

MadButterfly provides a framework to seperate the UI presentation from the program as much as possible. In this tutorial, we will demonstrate how to write a file browser in the correct way under the MadButterfly.

What's in a file browser?

In a file browser, we need to read all files from the current directory and display the list for the users to select. In addition, we might need to show the preview of the current selected file object. According to the above definition, we have the following elements.

• Current directory
• File scanner
• File object list
• File object viewer
• File object list viewer
• Current position in the file object list

By using the above elements, a file browser need to * Use file scanner to scan all files under a directory. * The purpose of the file scanner is to generate file object list gradually. It will scan one file at a time and collect some metadata for this file and convert it into a file object and add the object to the file object list. * Once the file object list has enough information, the file object list viewer will display it in the UI.

Therefore, the procedure will be

• When we enter a new directory, the file scanner will enter the scan mode to generate file object list from the first one to the last one.
• The UI will request the Current position of the file object list from the filescanner and wait for the response.
• When the request range of items are all ready, the file scanner will notify the UI to draw the file object list on the appropriate items.
• UI will request the detail information from the file object and use them to change the SVG document to reflect the infrmation of the current selected file object.
• When user press enter to play the current selected file object, the UI will
  • Request file scanner to scan a new directory if the current selected file object is a directory
  • Request the file object to play the file if it is a regular file object.

According to these descriptions, we need to implement the following actions. * file_scanner_start * file_scanner_request_range * file_object_play

and the following events * file_object_range_ready * file_object_play_ready * file_object_play_end * file_object_play_paused

The presentation layer

The SVG is used as the presentation layer under the MadButterfly. Unlike the resource file in other GUI toolkit, the MadButterfly expect the SVG to play more roles. Under the MadButterfly, the UI can be changed dramatically without recompiling the C modules. In order to achieve this, the C module will become passive modules which provide information and actions for the presentation layer to request. When we want to implement a file browser, we will write a file scanner and provide the above actions and events. When we write the file scanner, we don't need to care about how the list are displayed. It scans all files and then put each of them into the file object list one by one. When the items inside the file object list satisfy any range request, the file scanner will send file_object_range_ready notification to the presentation layer.

From the presentation layer, we can focus on how the file object list are rendered. It's logic is very simple as well. A file_scanner_start will be sent in the beginning when we request a new range to be displayed. When the presentation layer receive file_object_range_ready, it simply display the file objects carry in the notification message. Therefore, the file browser will become.

• Send filescanner_request_range
• Associate the notification file_object_range_ready to an animation which can transit from the current state of the list to the next one.
• It can be as simple as update the content of the list by using the new information.
• It can be very complex to implement a fade in/out effect by using the old and new list.

Therefore, the UI can be modeled as * Associate an key notification to an file_scanner_range request * Associate an file_object_range_ready notification to an animation

We can write this in an XML file as

<associate key="down">   
    <request item="file_sacnner_down" /> <request item="file_scanner_request_range" /> 
    <associate type="once" event="file_object_range_ready" onEvent="fillContent" > <animation id="scrolldown" /></associate>
</association>
<associate key="up">   
    <request item="file_sacnner_up" /> <request item="file_scanner_request_range" /> 
    <associate type="once" event="file_object_range_ready" onEvent="fillContent" > <animation id="scrollup" /></associate>
</association>

The fillContent can be implement in C module or in javascript embedded in the SVG file. In this way, we can implement a file scanner which can be used to implement any style of the file browser.

In addition, we can freely add file browser to any UI easily. The only thing we need to do is to put the above lines to any scene. In addition, we can groups these association as a group of association.

<associations id="fs">
    <associate key="down">   
        <request item="file_sacnner_down" /> <request item="file_scanner_request_range" /> 
        <associate type="once" event="file_object_range_ready" onEvent="fillContent" > <animation id="scrolldown" /></associate>
    </association>
    <associate key="up">   
        <request item="file_sacnner_up" /> <request item="file_scanner_request_range" /> 
        <associate type="once" event="file_object_range_ready" onEvent="fillContent" > <animation id="scrollup" /></associate>
    </association>
</asociations>

Then, these binding can be added into any scene by reference

<associations ref="fs"/>