Events
This namespace contains functionality related to event handling, mutation observers and keyboard/mouse tracking.
OnReady
The OnReady event fires when Fit.UI and the page is loaded. It is safe to assume that everything is ready to use when this event fires. The code below demonstrates how to register an event handler that is automatically executed when OnReady fires.
Fit.Events.OnReady(functino()
{
Fit.Controls.Dialog.Alert("Fit.UI and website is loaded and ready");
});
We can also hook into the document even earlier using OnDomReady. At this point the DOM is ready, but resources such as images may not have been fully loaded yet.
Event handlers
Adding and removing event handlers are significantly easier with Fit.UI than traditional JavaScripts - especially the latter since removing event handlers do not require the developer to keep a reference to the callback function, making it easier to leverage the benefits of anonymous functions.
AddHandler and RemoveHandler
// Register event handler that only fires the first time the event occures.
// The type of event is specified without the traditional "on" prefix.
// Therefore, "onclick", "onmouseover", and "oncontextmenu" is simple specified
// as "click", "mouseover", and "contextmenu".
var eventId = -1;
eventId = Fit.Events.AddHandler(document, "click", function(e)
{
Fit.Controls.Dialog.Alert("You clicked on my page");
Fit.Events.RemoveHandler(document, eventId);
});
Naturally events can also be captured (read more about
event bubbling and capturing) although this is not supported on IE8. To use capturing, simply pass True as the 3rd argument, and the event handler as the 4th argument.
Fit.Events.AddHandler(document, "click", true, function(e)
{
alert("Event was fired during the capture phase");
});
Use GetEvent(..) and GetTarget(e) to make sure event handlers work across all browsers.
GetEvent and GetTarget
eventId = Fit.Events.AddHandler(document, "click", function(e)
{
var ev = Fit.Events.GetEvent(e);
alert("Mouse button clicked: " + ev.button);
var target = Fit.Events.GetTarget(e);
alert("Element type clicked: " + target.tagName);
});
Use StopPropagation(e) to prevent event handlers on elements further up the DOM hierarchy to be notified about a given event, PreventDefault(e) to suppress the default behaviour in the browser (e.g. suppressing the context menu), and Stop(e) to both stop propagation and prevent the default behaviour.
StopPropagation, PreventDefault, and Stop
Fit.Events.AddHandler(document.body, "contextmenu", function(e)
{
// Do not let event propagate up the DOM hierarchy
Fit.Events.StopPropagation(e);
// Prevent browser from opening the context menu when right-clicking
Fit.Events.PreventDefault(e);
// Same as calling both StopPropagation(e) and PreventDefault(e)
Fit.Events.Stop(e);
});
Mutation observers
Using Fit.UI developers can set up simple mutation observers. These can be used to invoke a function when attributes or dimensions of a DOM Element is changed.
// Register CSS class "Mobile" if user resizes window below 800px,
// or register CSS class "Desktop" instead, if user resizes window above 800px.
Fit.Events.AddMutationObserver(document.body, function(elm)
{
if (document.body.offsetWidth < 800)
{
Fit.Dom.RemoveClass(document.body, "Desktop");
Fit.Dom.AddClass(document.body, "Mobile");
}
else
{
Fit.Dom.AddClass(document.body, "Desktop");
Fit.Dom.RemoveClass(document.body, "Mobile");
}
});
It is even possible to monitor the entire hierarchy underneath a given node by passing True as the 3rd argument, although this should be done with careful consideration as it is more performance demanding.
Fit.Events.AddMutationObserver(document.body, function(elm)
{
// This handler fires if target or ANYTHING
// within is changed - even character data!
}, true);
Since mutation observers require the browsers to track changes to the DOM, disconnecting observers when no longer needed is highly recommended. Use the disconnect() function to stop observing a target.
Fit.Events.AddMutationObserver(document.body, function(elm)
{
alert("Body changed");
disconnect(); // Do not track additional changes
});
Keyboard and mouse tracking
Fit.UI tracks the keyboard and mouse, making the current state of these devices easily accessible.
GetModiferKeys
var keys = Fit.Events.GetModifierKeys();
var keys = // Example object returned from GetModifierKeys
{
Shift: false, // Whether Shift key is currently pressed
Ctrl: false, // Whether Ctrl key is currently pressed
Alt: false, // Whether Alt key is currently pressed
Meta: false, // Whether Cmd/Windows key is currently pressed
KeyDown: 28, // Key currently pressed (key code)
KeyUp: -1 // Key currently released (key code)
}
GetPointerState
var pointer = Fit.Events.GetPointerState();
var pointer = // Example object returned from GetPointerState
{
Buttons:
{
Primary: false, // Whether primary button on mouse is pressed
Secondary: false, // Whether secondary button on mouse is pressed
Touch: false // Whether a touch on a mobile devices is currently occurring
},
Coordinates:
ViewPort: { X: 39, Y: 200}, // Pointer/touch position within viewport
Document: {X: 39, Y: 200} // Pointer/touch position within document
},
Target:null // DOM Element being targeted (pressed/touched)
}