jQEm - Interact with the base 'em' unit

jQEm is a plugin for the jQuery JavaScript library that detects changes to the computed value of 1em and triggers an event as appropriate. This document describes jQEm version 0.2.


Author

Dave Cardwell (jQuery plugins)


Changelist

  1. v0.2 - Thursday 24th August, 2006

  2. v0.1 - Monday 21st August, 2006


Usage

The uncompressed source code is heavily documented. After reading this synopsis, that would be a good place to look.

Initialisation

By default, jQEm will initialise when $(document).ready() is triggered. You can stop this behaviour by $.jqem.auto(false)ing, and can then perform the setup subsequently using $.jqem.init().

$.jqem.auto( false );
var test = $.jqem.auto(); // is automatic initialisation enabled?
$.jqem.init();

Binding and unbinding

jQEm triggers a global event 'emchange' when a change is detected. As such you can use the bind and unbind methods outlined in the jQuery documentation.

var myFunc = function() { ... };
$('#foo').bind( 'emchange', myFunc );
$('#foo').unbind( 'emchange', myFunc );

With jQEm you can also bind functions to the 'emchange' event without having to tie them to a jQuery object using a similar syntax.

$.jqem.bind( myFunc );
$.jqem.unbind( myFunc );

Triggering

If you want to manually cause an 'emchange' event to trigger you can use the following function. Passing true will force the event to trigger, otherwise it will only be triggered if a check to see whether or not the value of the 'em' unit has changed since the last check passes. You can also provide an array of arguments which will be passed to every event triggered.

$.jqem.trigger();
$.jqem.trigger(true);
$.jqem.trigger( false, [ 'foo', 'bar', 42 ] );

Updating

When auto-updating is enabled, any changes to the value of the base 'em' unit that are detected will cause an 'emchange' event to trigger. Updating is turned on by default by the $.jqem.init() function.

// Start updating
$.jqem.start();

// Is updating currently active?
var active = $.jqem.active();

// Stop updating.
$.jqem.stop();

If available, jQEm uses Internet Explorer’s setInterval method to detect updates to the value of the base 'em' unit. Otherwise we have to constantly poll the document looking for changes. You can fetch and modify the delay (in milliseconds) between checks for the latter with the following function.

// The current delay
var delay = $.jqem.delay();

// Change the delay (from the next time the updater is explicitly start()ed)
$.jqem.delay( 100 );

The value of 'em'

You can fetch the most recent and the previous calculated values of 1em with the following functions.

var current  = $.jqem.current();
var previous = $.jqem.previous();

Notes

It is recommend that this plugin is the first JavaScript file you include after jQuery itself. Subsequent files and plugins can then detect its presence and utilise it as desired.

When the document is loaded an <i> element is prepended to the beginning of the <body>, though positioned absolutely outside of the viewable area. This has a width of 1em and is used to detect changes in the base font-size. I chose <i> since it is deprecated, has no semantic meaning, and probably won’t get much use any more. Nevertheless, be aware of its presence.


Download

jQEm is dual-licensed under the MIT and GNU GPL licenses, so if you can use jQuery you can use this plugin.

If you find a use for jQEm I’d love to hear about it. Also, a link to this site wouldn’t go amiss!

I recommend you download the version that I’ve compressed with Dean Edwards’ packer which weighs in at 1.7K. Alternatively I make the heavily documented, uncompressed version available at 9.2K.


Bugs

jQEm v0.2 has no known bugs.


Testing