Browser

Qbix includes two methods for determining browser characteristics.

One is Q.Browser.getScrollbarWidth(). It determines the width that a scrollbar would take up on that particular platform.

The other is Q.Browser.detect(). It returns the following information:

• name: the browser name
• mainVersion: the main version number
• engine: webkit, gecko, presto, etc.
• OS: Mac, Win, Linux, iOS, Anrdoid, etc.
• device: iPhone, iPod, iPad, Android, etc.
• isWebView: whether this is inside an app

When initializing the page, Qbix also computes the following values for you:

• Q.info.isTouchscreen: whether this is touchscreen
• Q.info.isTablet: whether this is a tablet
• Q.info.isMobile: whether this is a mobile phone
• Q.info.formFactor: tablet, mobile or desktop

And it also adds the following class names to the html element, for you to make use of in your CSS:

• Q_touchscreen or Q_notTouchscreen
• Q_mobile or Q_notMobile

Pointer

Qbix also includes methods for dealing with pointers and coordinates on various platforms. Found under Q.Pointer, they integrate well with the rest of Qbix, so you are encouraged to use them:

• start: use this as the event name when listening for touchstart / mousedown
• move: use this as the event name when listening for touchmove / mousemove
• end: use this as the event name when listening for touchend / mouseup
• enter: use this as the event name when listening for touchenter / mouseenter
• leave: use this as the event name when listening for touchleave / mouseleave
• click: use this as the event name when listening for a click
• fastclick: use this as the event name when listening for a "faster" click
• touchclick: like click but works on touchscreens even if viewport moves during click (such as if onscreen keyboard disappears)
• cancelClick(): call this if you want to cancel a click or fastclick
• onCanceledClick: an event that is fired when it is time to cancel a click
• canceledClick: you can check this if you still use your own events
• focusin, focusout: use for cross-browser focusin and focusout event names
• wheel: use for cross-browser wheel event name

Here are additional functions you can call:

• windowWidth, windowHeight: cross-browser way to get the dimensions of the window
• scrollLeft(), scrollTop(): gives the document's scrollLeft, scrollTop in a cross-platform way
• getX(event), getY(event): extract the x and y coordinate relative to the document from the event
• elementFromPoint(pageX, pageY): pass x and y coordinates here relative to the document
• target(event): extracts the target element from the event
• relatedTarget(event): extracts the related target element, such as when dragging one over another
• touchCount(event): how many fingers are involved, or 1 for a mouse button
• which(event): normalizes the mouse button to 0-left, 1-middle, 2-right.
• offset(event): computes the offset of an element relative to the browser
• preventTouchScrolling: call this to prevent the rubber band scrolling effect on the document

Animation

Qbix also helps support Javascript animations through the Q.Animation class. You are encouraged to use this after considering animated GIFs and CSS animations first.

var a = new Animation(
  callback, 
  1000, // duration in milliseconds
  Q.Animation.ease.linear,
  {extra: "data"} // to pass to the callback
);

function callback(x, y, params) {
  // 0 <= x <= 1 is the fraction of time elapsed
  // 0 <= y <= 1 is the output of ease function
  // params is {extra: "data"}
}

a.play();
a.pause(); // sometime later
a.rewind(); // sometime later
a.play(); // sometime later

Audio

Qbix lets you play audio through the Q.Audio class.

Dialogs

Since Qbix aims to present a consistent interface across all the social apps it powers, it includes default functionality for presenting dialogs and overlays. Here are the methods with their options:

Q.alert(message, options)

• title: the title of the dialog
• onClose: function or event

Q.confirm(message, callback, options)

• title: the title of the dialog
• ok, cancel: any html to override contents of Ok and Cancel buttons, respectively
• noClose: set to false to show a close button
• onClose: function or event

The callback receives true, false or null depending on whether the user clicked/tapped Ok, Cancel, or closed the dialog, respectively.

Q.prompt(message, callback, options)

• title: the title of the dialog
• placeholder: any placeholder to put in the textbox
• ok: any html to override contents of Ok button
• noClose: set to false to show a close btuton
• onClose: function or event

The callback receives the entered value as a string, or null if the user closed the dialog.

Q.Dialogs.push(options) is used to show custom dialogs, and takes the following options which provide alternative ways of filling the dialog box:

• title: default title of the dialog
• content: default content of the dialog
• dialog: if provided, HTMLElement or jQuery object containing already prepared dialog html, which includes elements with classes 'Q_title_slot', 'Q_dialog_slot' and appropriate content in them.
• className: any classes you'd like to add to the dialog element
• mask: set to false if you don't want to mask the contents behind the dialog
• fullscreen: show the dialog as fullscreen. Defaults to true on Android.
• appendTo: element to which the dialog should be appended. Defaults to the body element.
• noClose: set to false to show a close btuton
• onClose: function or event
• beforeLoad: occurs before the dialog is loaded
• onActivate: occurs after the dialog contents have finished activating
• beforeClose: occurs before the dialog is closed
• onClose: occurs after the dialog is closed

Q.Dialogs.pop() is used to close the topmost dialog on the stack, if any.

By using the above methods to show your dialogs and alerts, not only will your apps work out of the box on every device, but users of Qbix apps will have a consistent experience and know what to expect. You can, of course, customize appearance of any elements using CSS.

Hints

Hints are a Qbix feature that is very useful for onboarding new users, or subtly getting them to becoe familiar with a particular page or tool. They can incorporate an animated hand pointer, audio, and more:

var First = {
  /**
   * Call this function, preferably synchronously
   * after a user action so that audio hints will work.
   * @method hints
   * @static
   * @param {String} name what to show the hint for
   */
  hints: function (name, extra) {
    var o = { 
      show: { delay: 500 },
      audio: { src: 'audio/hints/location.mp3' }
    };
    switch (name) {
      case "location": 
        var $ls = $('.Places_location_set');
        if ($ls.length && $ls.is(':visible')) {
          Q.Users.hint('First/location', $ls[0], o);
        }
        break;
      ...
    }
  }
};
... then somewhere in the code:
First.hints('location');