The BEST Profiler for Flash

With more than 10 innovative profiler tools, The Miner is the most complete solution for optimizing Flash content. Using a lightweight immersive approach, this profiler can hook on anything made in flash, which let you profile and debug anytime, as needed.

Tutorial: Using custom UserEvents

This tutorial will show you what is a UserEvent and how you can use them to do simple event reporting in your application
This PRO feature can only be used when using the SWC integration.

The event system is made in such a way that it's very easy to trigger basic events,
but it can also support a whole set of properties that can help you expose data in a more efficient way.

1. What is a UserEvent
A UserEvent is an event created by the developer in the application that will communicate with TheMiner to show up in a specific tab of TheMiner (UserEvent tab).
The event can be pushed to TheMiner in two ways:
  • TheMiner.AddBasicUserEvent(aEventName:String = null, aEventValue1:* = null): UserEventEntry
  • TheMiner.AddCustomUserEvent(aEventName:String = null, aEventInfo:String = null, aEventValue1:* = null, aEventValue2:* = null, aStatusBarLabel:String = null, aStatusBarProgress:Number = -1, aStatusBarColor:uint = 0xFF000000, aEventSortPriority:int = 0, aEventVisible:Boolean = true, aError:Boolean = false): UserEventEntry

Let start by defining the complete structure of an event

public class UserEventEntry extends Event
	public static const USER_EVENT:String = "TheMinerUserEvent";
	public var Name:String = "";
	public var Info:String = "";
	public var StatusColor:uint = 0xFF888888;
	public var StatusLabel:String = "";
	public var StatusProgress:Number = -1;
	public var Value1:String;
	public var Value2:String;
	public var Id:int = 0;
	public var Priority:int = 0;
	public var Visible:Boolean = true;
	public var IsError:Boolean = false;			

These are all the properties that "can" define a UserEvent.
Now the easiest way to demonstrate how this works is by using examples.

2. Triggering UserEvents
//Adding the most simple form of event
TheMiner.AddBasicUserEvent("BasicEventName", 5.7);

//Adding another simple event
var userEvent:UserEventEntry = TheMiner.AddBasicUserEvent("BasicEvent2", 2);

The Result:

Has you can see, new events are pushed on top of older events.
There are also a few very important tools that you can use to work with your events.
  • Error filter: Toggle button to show only events that have the ErrorFlag=true
  • Content Snapshot: Copy to clipboard every single event that have been dispatched. THE WHOLE THING
  • Copy to clipboard: Copy to clipboard a single line with all its fields
  • Search Filter: Will show only lines containing what has been entered in the textbox

3. Using custom UserEvents
Let's use some more parameters to define a Progress Event
//Using status/progress
//TheMiner.AddCustomUserEvent(EventName,EventInfo, Value1, Value2, StatusLabel, Progress);
TheMiner.AddCustomUserEvent("ProgressEvent", "Basic progress", "5", 7.5, null, 0.75);

//Setting a progress bar Color (reflecting progress
//TheMiner.AddCustomUserEvent(EventName,EventInfo, Value1, Value2, StatusLabel, Progress);
TheMiner.AddCustomUserEvent("ProgressEvent", "Progress with ProgressBar in color", "Val_X", "Val_Y", null, 0.75, 0xFFFFcc55);

The Result:

We can see here that values can be either a String, Number, or whatever is printable.
Again, events are stacked one on top of the others
The progress value used is always between 0 and 1. Here, we used 0.75 (75%)

We can also use StatusLabel to replace progression value.
Let's say you would trigger events when downloading a file and when a file is completed.
//Using status label instead of progress
TheMiner.AddCustomUserEvent("Progress", "Progress with Progressbar + StatusLabel", "Val_X", "Val_Y", "Completed", 1, 0xFF99cc55);

//Using status label instead of progress
TheMiner.AddCustomUserEvent("CustomName", "CustomInfo", "Val_X", "Val_Y", "Downloading", 0.25, 0xFFFFcc55);

The Result:

Another property we can use is the error flag.
Here is how we create an event, then set its flag to true
//Using Error event
var ue1:UserEventEntry = TheMiner.AddCustomUserEvent("CustomError", new Error("MyError").name, "Val_X", "Val_Y", "Custom Label", 0.25, 0xFFFFcc55);
ue1.IsError = true;

The Result:

And if we toggle error filter button, only the errors shows on screen:

Another property you can use is the priority.
New events always appear on the top of the others, except when using priority.
Let's first add a higher priority even, then a normal priority one:
//New events always appear on the top of the others, except when using priority.
//Higher priority mean the line will stay on top of lower priority event
TheMiner.AddCustomUserEvent("PriorityEvent", "Higher priority", "-", null, null, -1, 0xFF000000, 1);

//Lower priority get pushed under higher priority in the list
TheMiner.AddCustomUserEvent("PriorityEvent", "Lower priority", "-", null, null, -1, 0xFF000000, 0);

The Result:

The last parameter here is the priority.
By setting a priority level to 1, we make sure that line will stay on top of all previous entry.

4. UserEvents are updatable
Since UserEventEntry are kept in memory, it is possible at any time to change any of the values of a dispatched event.
Let's create an event that will simulate a file being loaded, showing with higher priority, updating the progress, and then resetting the priority when the file is complete.

//Updatable event
//Higher priority during update, resettingpriority when compete.
var t:Timer = new Timer(200)
var ue2:UserEventEntry = TheMiner.AddCustomUserEvent("UpdatableEvent", null , "-", null, null, 0, 0xFFFFcccc,3);
t.addEventListener(TimerEvent.TIMER, function(e:TimerEvent):void {
									ue2.StatusColor = 0xFF333300 + ue2.StatusProgress*255
									ue2.StatusProgress += 0.01;
									ue2.Value1 = String(int(ue2.StatusProgress * 10000) / 10000);
									if (ue2.StatusProgress >= 1)
										ue2.Priority = 0;

The Result:
Progress bar is moving, line is on top
Progress bar is moving, line is on top
Progress bar is complete, line goes down

5. Searching in all events
You can use the Search Filter box to enter anything. Events will be filtered from their name and info
Entered search filter "cus"