Interface Development Guide

Interface Development Guide
Interface Development Guide
Page: 1
CQC User Interfaces
Interface Development Guide
(For CQC Version 4.8)
Last Edited: October 11, 2015
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 2
Table of Contents
Table of Contents ...................................................................................................... 2
Content Summary ...................................................................................................... 6
Preliminary Notes ...................................................................................................... 6
Syllabus ............................................................................................................... 6
Prep-work ............................................................................................................ 6
Overview ................................................................................................................ 7
Templates and Widgets ............................................................................................. 9
The Big Picture .................................................................................................... 10
Actions ........................................................................................................... 10
Variables/Runtime Values ..................................................................................... 10
Navigation ....................................................................................................... 11
Images ............................................................................................................ 11
Popups/Popouts ................................................................................................. 12
States ............................................................................................................. 13
Focus ............................................................................................................. 13
Triggered Events in the Interface ............................................................................ 13
Gestures .......................................................................................................... 14
The Interface Editor ................................................................................................. 15
The Widget Palette ............................................................................................. 17
Hot Keys .......................................................................................................... 18
Widget Selection/Manipulation ............................................................................... 19
Image Management ............................................................................................. 19
Bulk Import ...................................................................................................... 20
Template Management .............................................................................................. 22
Search and Replace .................................................................................................. 23
Actions in Templates ................................................................................................ 24
Widget Types ......................................................................................................... 29
Configuring Widgets ............................................................................................... 32
Action Palette...................................................................................................... 32
Attribute Tabs ..................................................................................................... 33
Common Attribute Tabs .......................................................................................... 33
Text Tab ......................................................................................................... 33
Action Tab ....................................................................................................... 36
Basic Tab ......................................................................................................... 37
Field Tab ......................................................................................................... 41
Image Tab........................................................................................................ 42
Images Tab....................................................................................................... 43
States Tab ....................................................................................................... 44
Browser Tab ..................................................................................................... 47
Variable Tab ..................................................................................................... 48
Xlats Tab ......................................................................................................... 49
Cut and Paste ...................................................................................................... 50
Widget Documentation .............................................................................................. 51
Template ........................................................................................................... 51
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 3
Timeouts ......................................................................................................... 51
Hot Keys .......................................................................................................... 52
Events ............................................................................................................ 52
Template Actions ............................................................................................... 52
Events Supported: .............................................................................................. 52
Commands Accepted: .......................................................................................... 52
Animated Image ................................................................................................... 54
Area Color Fill...................................................................................................... 55
Boolean Image ..................................................................................................... 56
Commands Accepted: .......................................................................................... 56
Boolean Text ....................................................................................................... 57
Commands Accepted: .......................................................................................... 57
Calendar ............................................................................................................ 58
Events Supported: .............................................................................................. 58
Commands Accepted: .......................................................................................... 58
Runtime Values Provided: ..................................................................................... 58
Check Box .......................................................................................................... 60
Events Supported: .............................................................................................. 61
Commands Accepted: .......................................................................................... 61
Runtime Values Provided: ..................................................................................... 61
Color Palette ....................................................................................................... 62
Events Supported: .............................................................................................. 62
Commands Supported: ......................................................................................... 62
Runtime Values Provided: ..................................................................................... 62
Command Button .................................................................................................. 64
Events Supported: .............................................................................................. 64
Commands Supported: ......................................................................................... 64
Cover Art Browser ................................................................................................. 65
Events Supported: .............................................................................................. 66
Commands Accepted: .......................................................................................... 66
Runtime Values Provided: ..................................................................................... 67
Searches.......................................................................................................... 68
Digital Clock ........................................................................................................ 69
Digital VU Meter ................................................................................................... 70
Commands Accepted: .......................................................................................... 70
Driver Image ....................................................................................................... 71
Enumerated Image ................................................................................................ 72
Commands Accepted: .......................................................................................... 72
Graphs .............................................................................................................. 73
List Browser ........................................................................................................ 74
Events Supported: .............................................................................................. 74
Commands Accepted: .......................................................................................... 74
Runtime Values Provided: ..................................................................................... 74
Line .................................................................................................................. 76
Live Tile............................................................................................................. 77
Efficiency ........................................................................................................ 77
Logo Image ......................................................................................................... 78
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 4
Commands Accepted: .......................................................................................... 78
Mapped Image ..................................................................................................... 79
Commands Accepted: .......................................................................................... 79
Marquees ........................................................................................................... 80
Media Category Browser .......................................................................................... 81
Events Supported: .............................................................................................. 81
Commands Accepted: .......................................................................................... 81
Runtime Values Provided: ..................................................................................... 81
Media Image/Media Repo Image ................................................................................ 82
Commands Accepted (Media Image): ........................................................................ 82
Commands Accepted (Media Repo Image): ................................................................. 82
Media Item Browser/Media Repo Item Browser ............................................................... 83
Events Supported: .............................................................................................. 83
Commands Accepted: .......................................................................................... 83
Runtime Values Provided: ..................................................................................... 83
Media Item Browser (Advanced)................................................................................. 85
Events Supported: .............................................................................................. 85
Commands Accepted: .......................................................................................... 85
Runtime Values Provided: ..................................................................................... 85
Media List Browser ................................................................................................ 86
Events Supported: .............................................................................................. 86
Runtime Values: ................................................................................................ 86
Commands Accepted: .......................................................................................... 87
Media Repo Text ................................................................................................... 88
Commands Accepted: .......................................................................................... 88
Numeric Text....................................................................................................... 89
Commands Accepted: .......................................................................................... 89
Overlay .............................................................................................................. 90
Events Supported: .............................................................................................. 91
Commands Accepted: .......................................................................................... 91
Runtime Values: ................................................................................................ 91
Progress Bar ........................................................................................................ 92
Commands Accepted: .......................................................................................... 93
Events Supported: .............................................................................................. 93
Slider ................................................................................................................ 94
Events Supported: .............................................................................................. 94
Commands Accepted: .......................................................................................... 95
Runtime Values: ................................................................................................ 95
Special Actions Button ............................................................................................ 96
Static Image ........................................................................................................ 97
Commands Accepted: .......................................................................................... 97
Text ................................................................................................................. 98
Commands Accepted (Static version only) .................................................................. 98
Events Supported (Static version only): ..................................................................... 98
Runtime Values (Static version only): ....................................................................... 99
Time Image ........................................................................................................ 100
Time/Date Text .................................................................................................. 101
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 5
Commands Accepted: ......................................................................................... 102
Toolbar ............................................................................................................. 103
Images ........................................................................................................... 104
Events Supported: ............................................................................................. 104
Commands Accepted: ......................................................................................... 104
Runtime Values: ............................................................................................... 104
Volume Knob ...................................................................................................... 106
Events Supported: ............................................................................................. 106
Commands Supported: ........................................................................................ 107
Runtime Values: ............................................................................................... 107
Weather Channel Image ......................................................................................... 108
Web Browser ...................................................................................................... 109
Commands Accepted: ......................................................................................... 109
Web Image......................................................................................................... 110
Commands Accepted: ......................................................................................... 110
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 6
Content Summary
This document is intended for CQC system managers who have installed CQC and are ready to create touch screen interfaces. The user
interface system is one of the most important means of customizing CQC, and there is a lot of flexibility, so there is considerable
information to digest in order to fully utilize it. This document provides the detailed information you need to get the most of out your
interface design efforts.
There are also a considerable number of tutorial videos on the web site, which visually demonstrate in a more quickly digestible form a lot
of the concepts discussed here. This document may only be required for the technical reference source after watching the videos.
Preliminary Notes
The user interface system is basically a WYSIWYG Interface Editor, and is based around the visual elements you drop onto the interface
as you build it. These are known as ‘widgets’. Each widget has various attributes that you can modify to control its appearance and/or the
actions they will cause when interacted with. Importantly, these widgets can send commands to each other or query status from each
other, making for a lot of flexibility. So the bulk of this document is an enumeration of each widget type, their attributes, how you will
interact with them, if at all, and what commands they accept and information they provide.
Syllabus
Other than the opening sections, which introduce core concepts and common attributes/commands of widgets, the ordering of the rest is
pretty arbitrary, so the widgets are just introduced in alphabetical order at the end, to make them easy to find.









Overview
The Interface Editor
Image Management
Template Management
Widget Types
Adding Widgets
Configuring Widgets
Widget Documentation
Summary
Prep-work
This document assumes that you have installed CQC, and that you have gone through the introductory material, such as the tutorial
videos, so that you understand the basic concepts of CQC and its user interfaces, and of actions which are a large part of user interface
design.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 7
Overview
The CQC User Interface system is the primary means via which end users will interact with CQC on a day to day basis, in the vast
majority of CQC installations. It allows you, the system administrator, to create graphical interfaces by which users of your CQC system
can easily invoke whatever actions you wish to allow them to invoke, and to see whatever device state information you wish them to see.
These can be anything from a simple set of buttons, to very elaborate and visual extravaganzas.
Here is one example, in this case closer to the elaborate end of the spectrum, which has been reduced and annotated to show some of
the common features of a user interface:
Here you can see many of the most common features of a CQC user interface. They will be discussed in depth below, but briefly here is a
description of the features you see in this interface.






Animated Images. Animated images can be used to display a sequence of images to provide basic animation. In the example
above, if the security of the room this interface is running in is violated, it will begin to blink.
Boolean Images. These display one of two images based on whether they are in a True or False state, based on internal state,
a field, or a global variable value. In the example above it shows a light’s off/on status.
Cmd Buttons. Command buttons are a means of making things happen. This can include changing the interface itself, such as
display another interface or changing the color of something and so forth and/or sending out commands to devices under CQC’s
control.
Check Boxes. Check boxes are very flexible. They both show a current state of an associated field via image and/or text, but
they can also invoke one of two configured actions when pressed, based on the state of that associated field. In the above
example it’s toggling the mute state of an audio player. They can be used in various other ways as well.
Digital Clocks. The digital clock displays current time info in a number of different formats.
Overlays. Overlays allow you to load up smaller interfaces into larger ones, swapping in various smaller interfaces as needed.
The large central area above is an overlay into which various activity-related interfaces can be loaded. This allows you to have a
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 8





main interface with common functionality that stays fixed, but to reuse the overlay area. There can be more than one on a given
template.
Sliders. Sliders graphically display a numeric value within some range, and allow you to modify the value by moving the slider
up/down or left/right.
Static Images. Static images are for putting fixed images on the interface, usually for decorative purposes, but they can also be
updated by actions to show different images if desired.
Text. Static texts allow you to place labels on the interface, i.e. text that doesn’t change (though it can be changed by commands
from other widgets if desired.) Dynamic texts allow you to display the value of a field or variable as text. In the example above,
there are some showing weather condition data, among other things.
Toolbars. The toolbar is a very convenient one that provides a scrollable list of command buttons. So that you can get a lot more
buttons into a given area of the screen than could otherwise fit. They are very useful as menus type objects as well.
Weather Image. A specialized image display that understands the weather condition codes and images of weather data feeds.
They graphically show a particular weather condition.
This is just a sample of the kinds of visual elements you have available to you for your user interface design, and you can create
extremely different sorts of looks and feels using these same features, and just changing their visual appearance. For instance, here is
another example of an interface that uses mostly the same types of features, but it presents a very different look and feel.
You can create pretty much any look and feel you want to have, since the CQC user interface system is not like a ‘skinning’ system in
which you put various looks over a fixed set of functionality. CQC is a completely open ended system, which does not assume any
particular set of devices being controlled or how you want to expose them to the user.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 9
Templates and Widgets
In CQC parlance, these interfaces are called 'templates', because they are empty templates into which live data is placed when the
interface is viewed, and because the term 'interface' is a little too general and overloaded. Commonly the term ‘interface’ refers to the
template as it is actually running on a touch screen, while template refers to the actual designed screen layout as stored in CQC. The
various buttons, LEDs, volume knobs, etc…, that you place on a template to display system state, invoke actions, and so forth, are
referred to as 'widgets' or 'interface widgets'.
There are a small number of fundamental categories that all widgets will fall into:




Static. These are for decorative or labeling purposes, or for local purposes. They are not associated with any field or variable,
and you give them a value at design time and that is what they display by default. They can though in most cases be modified at
viewing time by commands sent to them by other widgets, and they are also often used to accept user input.
Dynamic. These are associated with a device field or a global variable, and they in some way update themselves at viewing time
to reflect the state of that field or variable.
Invocation. These invoke an action, such as a button or a volume knob. These may also be dynamic in that they change
appearance based on some field value, and they also may commonly have their appearance modified by commands sent to
them by other widgets.
Containment. There are some specialized widgets that just contain other widgets. The overlay described above in the
introductory section is an example. These types of widgets generally have little or no appearance of their own, and are purely for
hierarchical organization, or screen real estate reuse purposes.
All widgets will be one of these types, but there are many that are more than one. For instance, the check box widget, which both displays
a current state and invokes one of two actions (true or false action) when clicked, or media browsing widgets which both display media
metadata information and with which you interact to make media selections for playback/preview.
Dynamic and invocation type widgets are the most important. These are what you will use to display the state of the devices under CQC’s
control and to get CQC to do things for you. Dynamic widgets can be associated with either device fields or global variables that you
create within your user interfaces. Associating widgets with variables inside the interface allows you to provide control purely local to each
computer running that interface, whereas device fields are global to the entire network.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 10
The Big Picture
The most important things you need to keep in mind when developing your templates are the following. Note that some of these may not
be important in any given case, according to how the user interacts with your CQC interfaces.










Actions
Navigation
Popups
Images
Variables
Runtime Values
States
Focus
Events
Gestures
Actions
Though much of the art of interface design is involved in creating a visually striking but interactively self-evident presentation, the other
big part of it is allowing the user to make things happen in an useful way, which you will do via various action invoking widgets. These
will allow the user to kick off actions that you have designed for them, to achieve particular changes in the system state. If you have not
gone through the tutorial videos on the web site, you should do that now so that you understand what actions are. There is also an
Action Reference document as well, which gets more into the details of actions.
By setting up the right actions, you can make the control of the system quite 'auto-magical' to your users, where a single press of a
button causes a number of coordinated operations to be invoked. And, since CQC provides powerful macro capabilities, and two-way
control of devices, your actions can be very smart about how they do their work.
Normally, when you configure an action, just the standard targets are available, which are System, Macro Engine, Devices, Event
Server, and the variables targets. For actions invoked within the interface system, widgets can also be targeted with commands. This is
a very powerful capability of CQC, and it allows you to create smarter displays without writing any code, it’s all point and click. There are
some generic commands, that all widgets will support, such as hide/show, and many widgets define type-specific commands such as
the cover art browser’s ‘Set Category’ command that can tell it to start browsing a particular media category.

To make a widget available as a target in actions, you just have to give it a name in the Basic tab of the widget’s attributes
dialog. It will show up with that name in the available targets list.
Interactive widgets tend to support action events like OnPress, OnRelease, OnDrag, OnClick, OnSelect, and so forth. These allow you
to do things in reaction to the user interacting with the widget.
See the “Actions in Templates” section below in this document for more information.
Variables/Runtime Values
Variables and runtime values are very important in user interface design. Variables and runtime values have been discussed in lower
level documents and tutorials, since they are key aspects of the action system. However, in the user interface system, they can become
extremely important. Some of the widget types provide fairly extensive information via runtime values when they are invoked by the
user, so that you can quickly have access to the data you need to decide what you want to do in the actions invoked. In particular the
media related widgets can often provide a number of runtime values.
For instance, if you click on a media title in the cover art browser, you will receive metadata information on the clicked title, via a set of
named runtime values. They called runtime values because they are only available when the interface is running in the viewer, not at
design time. They tell you about things that happen dynamically as the user is doing things.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 11
Variables are often used extensively as well. There are two key ways in which they are used. One is that there are many dynamic
widget types which can be based on either a field or a global variable. And variables are often used to maintain information that is
required across templates or popup invocations. For instance, if you supported a browsing and a now-playing interface, and you wanted
to go back to the one that was last displayed when the user clicks on the Media icon, you could remember that in a global variable.
Since it is global (to the viewer window, i.e. as long as the viewer is running), it will still be there the next time the user clicks Media, and
you can use it to decide which media interface to display initially.
Navigation
Navigation in the user interface system involves moving from one interface to another to another in order to give the user the information
he wants or allow him to do what needs to do. You place buttons, toolbars, etc… on your templates which invoke other templates,
creating a set of related templates that your users can move between, to access functionality and information you wish to make
available to them. This paradigm is very commonly used in many interactive touch screen systems.
There are two basic navigation operations. One is to load a completely new template, replacing the existing one. So it's a lot like the
web browser paradigm, where you click on a link and move to a new page, which replaces the page you are on. By putting buttons on
each template that allows them to move to other templates, you can create a web of templates that has some sort 'topology' that you
desire. You can create a two layered system in which each link on the main template takes you to a second level template and it only
has a button that takes you back, or you can create a more multi-dimensional or ‘hyper-link’ type connections, as you desire.
The interface system also supports 'overlays', in which you have a main template on which you place one or more overlay widgets,
which are just named container objects. You can then draw other templates the same size as the overlays, and cause them to be
loaded into the overlays upon some user interaction. This is often very convenient because you can have a set of widgets in the main
template that are always there (often a toolbar or set of buttons along one or more edges) and just load up different templates into the
overlay area to access different functionality. In the ‘link to a new template’ paradigm discussed above, you would have to redundantly
draw those common widgets into every top level template, which is not required when reusing an overlay to display different content
over time.
Of course you can combine the two schemes, so that some link buttons load completely separate templates, which in turn might contain
overlays. And the overlay system is recursive, i.e. a template loaded into an overlay can itself have a still smaller overlay and buttons on
it that load various things into that nested overlay, and so on. Though as a practical matter two levels of nesting is usually as far as you
would go for reasons of screen real estate available.

For the most part, widgets can only send commands to other ‘sibling’ widgets, i.e. those in the same template that they are in.
The reason being that there is no way to directly address a widget in another template.

However, for overlay loading there are some special commands that you can use to send commands to overlays unavailable at
design time, to make them load new content. See the Actions in Templates section.

To make an overlay reload itself, any of its currently loaded child widgets can just call the LoadNewTemplate command on the
Intf.Viewer target. This always addresses the current container of the invoking widget, either the template itself or the overlay
that contains the widget.
Another option, often used in conjunction with one of the above, is that of pop-ups, which are much like dialog boxes in Windows, where
the program wants to get some information from you, or tell you something, in a way that requires you to acknowledge or deal with it
before you do anything else. I.e. it pops up over the existing program interface and you have to dismiss it before you can continue. See
the Popups/Popouts section below for more information.
Images
Though you don't have to use any, the interface system can make extensive use of bitmapped images. Perfectly useful and nice looking
interfaces can be created without using any images, and if done well can actually look quite stylish. But if you want to create stunning
looking interfaces that make the neighbors green with envy, understanding how to use images in your interfaces is very helpful. The
actual use of images depends on the type of widget, so the details will be discussed later in the widget-specific areas of this document,
but the big picture issues will be covered here.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 12
CQC comes with a very nice set of useful images for interface design. But you can upload any images to CQC that you want to use. The
shipped images are of the smallish type, such as you would use with buttons, LEDs, check boxes, and so forth, though there are various
panels and background images as well.
One issue of concern when you upload images to CQC is 'transparency'. Some images include both foreground and background
elements that are important, and therefore they are designed to completely fill their rectangular area. Others only have foreground
elements, and the background is supposed to be transparent, i.e. whatever is under the image should show through. CQC supports
both ‘color based’ and ‘alpha based’ transparency.
Color based transparency allows you to indicate that wherever a given color is used in the image, those areas are supposed to be fully
transparent. Alpha based transparency allows you to indicate a ‘blending factor’ for each individual pixel, which controls how much of
the background under it shows through. Alpha transparency is much more powerful, but also makes the images bigger and requires
faster video hardware to be really snappy when lots of them are used.
These days, color based transparency is seldom used because modern systems are quite powerful enough to handle alpha based
transparency and the results are enormously better than with color based transparency. Alpha based images can slightly reduce the
opacity of the pixels around the edges of the foreground elements of the image, allowing them to blend in very cleanly with the
underlying content, whereas color based images often have jagged edges because a pixel is either completely transparent or
completely opaque.
CQC also allows you to adjust the overall transparency of images on a per-image basis. This overall ‘opacity’ setting is in addition to any
color or alpha based transparency the image might have.
Popups/Popouts
In most any user interface system, there will be a means by which the program can temporarily halt your interaction and pop up over the
main display some sort of smaller display which it requires you to deal with before you can continue. These are often called Dialog
Boxes in the Windows world. They ask the user questions and get Yes/No or Proceed/Cancel type of responses, which the program
then acts on. The underlying program interface will be locked out until you dismiss this dialog box, because the program cannot
continue until you provide the required information.
CQC’s interface system provides a similar mechanism, called Popups. These act just like dialog boxes do in the Windows GUI, except
that they can be much more visually attractive and fully integrated into the look and feel of your user interfaces. They are themselves
templates, which are invoked using a special action command. Until the user dismisses the popup, the underlying template is locked
out. It is important to note that the action that invoked the popup is also paused, waiting for the results to come back from the popup, at
which point it picks up again and can react to the information gotten from the user by the popup.
So Popups allow you to get information you need, and then come back and act on that information in whatever way you want. This is an
extremely powerful mechanism, which allows you to create truly interactive sets of user interfaces. You can also create very reusable
popups that save you vast amounts of time. For instance, a popup that gets an either/or type of decision from the user can be set up so
that the invoking action provides it with the text message to display and the text to put on the two buttons that lets the user choose either
this or that. Depending on which button the user presses, the invoking action can then do one thing or another. This type of popup can
be reused again and again.
Popouts are just a variation on popups which, instead of just popping up, can slide out in one of four directions, usually from the edges.
It’s just a nice way to make the interface look interesting, but other than sliding out and back in again, it is functionally equivalent to a
regular popup.
By default, popups fade in and out. If that an issue for you for some reason, then you can enable or disable fades as desired.
Typically popups are dismissed by the user taking some action, such as an exit button or making a selection from a list presented by the
popup and so on. On a keyboard based system you can also press Escape to exit a popup. Upon exit the popup/popout can return a
result code, which the invoking template can react to, which makes it a very powerful tool for getting answers from the user about
whether to do this or that or not.
There is a tutorial video on popups which will probably make the subject a lot easier to understand, since it can show you how it works
instead of trying to describe it.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 13
States
In order to allow you to create interfaces which adapt to circumstances, each interface you draw can have a set of associated 'states',
each of which will at any particular time evaluate to a true or false value. Most widget types can use these states to either hide
themselves or, if they accept use input, to refuse to take any input from the user.
The primary use of these states is to deal with devices that will only take particular commands or provide particular information when the
system is in a particular state. So you can set up states that evaluate to true or false when the system is in those states, and have the
affected widgets either hide themselves or refuse to accept input in response to these states.
Note that the main visibility setting of a widget, which is controlled by the Hide/Show command and by the Initially Invisible check box in
the Base tab, is separate from the states driven visibility. The main setting always overrides states. So if the main setting is hiding the
widget, states won’t make it visible. If the main visibility setting allows the widget to be visible, then state driven visibility can hide or
show it, based on how the states evaluation.
Focus
Navigation also includes the issue of ‘focus’. If you are familiar with standard Windows programs, one of the interactive controls always
has some sort of visual emphasis that it is the control that is getting user input. So if you press Enter, that button will be pressed. Or if
you start typing, that entry field will get the characters. That control is said to have the ‘input focus’.
There are multiple ways to use CQC interfaces, and according to how you use them, you may or may not want to support this type of
input focus. If you are using them on a touch screen, then it doesn’t make sense, because in that case there is no keyboard. The user
just touches what he wants to interact with. If you are primarily using interfaces on a standard computer, via the keyboard, then you may
want to support focus. If you are displaying the interfaces on the projector, and controlling it via remote control or a tablet PC, then you
definitely do want to provide for focus movement.
Focus is handled via a set of visual indicators, mostly image based. For instance, there is a Focus image available on any widgets that
support user interaction. You can make the widget change appearance when it has the focus by making it display a different image. You
can also set the focus image to the same as the non-focus image but use transparency differences to make the focus button stand out.
For instance, you might make the non-focus image very transparent and the focus image fully opaque. Then, when you move the focus
around, the one that has the focus stands out clearly.
Note that some widgets have ‘internal focus’, i.e. the focus moves through multiple locations within them. The cover art browser is an
example, since it shows multiple CD/DVD cover art images and in order to allow you to move to a particular one and select it, the focus
has to move within it. The toolbar and the various horizontal/vertical list browser widgets are other examples. These types of widgets will
indicate their internal focus in ways that are appropriate for them. If focus is not enabled, these widgets do not indicate any focus
position.
Focus is enabled by a setting on the top level template’s attributes. The value of this setting in any templates loaded into overlays is
ignored, and the top level template’s value always controls whether focus is used or not. Note also that when using CQC in the 10’
Interface type of scheme, i.e. on the projector screen, then the focus system and the Interface Viewer’s remote control interface work
together to allow you to drive the interface via remote control or another CQC client, such as a tablet PC or other hand held device.
Triggered Events in the Interface
For the most part, your user interfaces will react naturally to changes in the devices that it is set up to display information from. You will
use things like dynamic text, binary and enumerated images, and so forth to display the status of devices and as soon as those devices
change, those widgets will update to show the changes. However, there are some cases where you want to take special action in the
case of a change in a device. So you can configure the interface such that it can receive event triggers (just as you configure the Event
Server), and this allows you to do things like make an overlay visible when the phone rings, to show caller id information, or to display
some warning information if a security breach occurs, and so forth.
The things you can do are limited within an event handler inside the IV, because of the possibility of interfering with the user who is
trying to interact with the user interface. So, many of the commands that are normally available are not there when you are configuring
such event based actions. For instance, it makes no sense to do field writes from an event driver action in an interface. If there were
more than one client out there running that interface (and there very often is), they would all start doing the same thing at once. Those
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 14
types of things are appropriately done in the Event Server. Events in interfaces are primarily there to make changes in the visual
characteristics of the interfaces to let the user know that something has happened.
You can read field values, but in general you should be careful about doing anything that could block or take time to complete because
the user is locked out from interacting with the system while the event is being processed (otherwise the two of them would be fighting
for control over the widgets that they both might be interacting with.) There would be no obvious reason to the user why it’s not
responding.
So use the event system very conservatively and mainly limit yourself to just visual updates. And also note that if you do something in
an event, it is your responsibility to make sure that you deal correctly with it happening multiple times. I.e. if you run some program for
the user when something happens, then that thing happens 5 more times in a row, you might end up with 5 instances of it running. So
be careful to deal with such things.
Note that when templates are loaded into overlays, any events configured on them are not maintained. Only the base template and the
base template of any pop-ups can have events defined. The events are evaluated starting with the base template and working up
through any pop-ups that might be layered over it. Only one event will run at a time, so if the base has an event configured and there is
a pop-up that also has one, the base runs first, then the pop-up runs.
The event will be held off if the user is currently actively interacting with the template. I.e. if the user is moving a slider or volume knob or
holding down a button, the event will be queued up and won’t be processed until they release, and if after any events that they might
cause have completed.
The commands available in events are strictly limited because they could create havoc if they attempted to do things in underlying
layers that invalidated the context in which a popup had been created. So mostly they are limited to fairly innocuous operations.
Gestures
As of version 4.5, the viewer is fundamentally gesture oriented. If you are on multi-touch hardware, then support for that will be
automatically installed. Else, faux support will be loaded which translates regular mouse movements into gestures, and non-multi-touch
touch screens look like a mouse to CQC, so they are covered in this way as well.
See the Interface Viewer Guide for details of how gestures work in terms of actual interaction. This document will only discuss them in
so far as they are relevant to design issues.
One key aspect of design is that of scrolling efficiency. You want your interfaces to respond quickly to touch and drag operations.
However, scrolling content such that it is very quickly responsive when you press and start moving is VERY complex, and the IV engine
jumps through ridiculous hoops to make it as efficient as possible. But, there’s just no way it can scroll large amounts of content
transparently over a background. If your machine is really fast it may do well, but it may seem a bit unresponsive and have a noticeable
delay when you start moving your finger. See the Interface Design Guide for more technical discussions on this front.
For maximum efficiency, design your interfaces so that ‘heavy’ scrollable content, particularly CABs or Advanced Media Item Browsers,
have non-transparent backgrounds. They can be either use a flat fill, or a gradient that doesn’t change in the direction of travel. I.e. in a
horizontally scrollable list, a vertical gradient doesn’t change in the direction that the content is scrolling. This allows the background to
be drawn into the scrollable image and the whole thing can be scrolled. For a transparent background, the whole content has to be
composited repeated over the background in each new position and that can be very heavyweight. Actually in the efficient scenario it’s
even better, in that the screen content can be moved over within the video buffer, and only the small uncovered bit has to be redrawn.
So it’s vastly more efficient.
Also keep in mind that text blurs can make the response slower, because blurs are quite CPU intensive and having to draw lots of them
very fast is difficult. Perhaps, when we’ve move to Windows 7 as our baseline, in the next release, we can make use of some graphics
hardware acceleration that will make blurs much faster.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 15
The Interface Editor
The Interface Editor is the tool via which you create user interface templates. It is one of the optional client side applications which can be
installed on any PCs in the network from which you wish to work on interfaces. As with all CQC tools, the interface system is fully network
distributed, so the interfaces you create are stored on the Master Server and immediately available to any other PCs on your network
which are running CQC. So use the Charmed Quark Controller item in the Start Menu, and pick the Interface Editor item to invoke the
editor. You will be presented with the following sort of screen.
The Interface Editor allows you to edit multiple templates at once, using a standard multi-document interface. The example image above
shows two templates opened in the editor.
Each of the editor windows consists of a drawing area where you draw the actual contents of the template, i.e. the drawing area
represents the template itself, and a larger workspace area that fills the rest of the available window area. The first time you run the
designer, it will often have a default size small enough that the default initial template size is bigger than the available workspace. So if
you size up the window, you will see the actual size of the template itself. You can move the mouse over the edges or corners, and then
click and drag to size the template.
The editor is very 'object oriented', in that each template is composed of various widget objects that you want to act on. You do so by
putting the mouse over it and right clicking to pop up an ‘action menu’ that indicates what actions you can apply to that object, or by
dragging them around with the mouse. You will also see the size and position of that item in the lower right side of the window. In the
example above, the mouse is over the template background itself, and you see its size and position displayed.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 16
The action menu is the same for all objects, but some items will be disabled if they are not appropriate for the target object and/or for the
target object's current state, and some may only be available if a single widget is selected.
The menu items available are as follows:













New. Create a new widget at the point where the mouse was clicked to pop up the action
menu. It will drop down a sub-menu that allows you to select the type of widget you want
to create.
Delete. Delete the selected widget(s). You cannot delete the main template widget, so it is
disabled in that case.
Search and Replace. This command is discussed below, and it allows you to modify
various types of widget attributes in a single operation.
Attributes. This one is always available, and invokes the attributes dialog for the selected
widget, allowing you to configure it.
Define States. Allows you to define the states for this template. States will be discussed
later. This one is not specific to the widget selected.
Size To Contents. Some widgets have contents whose size is known at design time, and
for those this item will be available. It will size the widget to fit around its current contents.
Set Size. Allows you to set the size of the target widget by typing in the values. This is
often used to force it to be a known size, and it can be more convenient in those cases
than by dragging the edge with the mouse.
To Back/To Front/Move Back/Move Forward. When sibling widgets overlap each other,
you need to control the order in which they are drawn, so as to make some show up on
top of others. In this case front and forward means towards you, i.e. on top of other
widgets, while back means away from you, meaning under other widgets. Since the
template itself has no siblings, only children, these are disabled in this case.
Group/Ungroup. Group or ungroup the selected widgets. Grouping widgets makes them
be treated as a single widget for selection, drag, and so forth.
Locked. You can lock widgets so that they will not be selected. This is often useful when you have an image or color fill widget
behind other widgets. Locking the image widget means you can swipe select the foreground widgets without the image widget
being dragged.
Cut/Copy/Paste. In order to save you a lot of time, you can copy and paste widgets that you have created, allowing you to
'clone' an existing widget with all the same attributes, then modify only those you want to change. Since we have no widget in the
clipboard, the copy and paste items are disabled. And since the template itself cannot be copied or cut, they would be disabled
for that reason as well.
Copy/Paste Attributes. In order to help you make various types of widgets have a similar look and feel, you can copy the
attributes of one widget and paste them into another. The target widget will take those attributes that it shares with the source
widget. This is often a convenient way to apply a common color scheme, font type, and forth to a set of widgets.
Copy Point. Copies the x,y pixel position (relative to the template origin) at which you clicked. This I used to ‘grab’ a point for
pasting into a command parameter later that needs a point value.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 17
The Widget Palette
The editor has a second top level window, which is the ‘widget palette’. When you have a fairly complex interface, there can be a good
number of widgets involved, and some of them will have default appearances that might not make them very easy to see, if not outright
invisible, and some will be covered by other widgets occasionally. In order to help manage the widget list, the widget palette provides a
listing of the widgets, in their ‘z-order’, which is the order that the widgets will overlay each other if they intersect, i.e. those further down
the list (higher z-order) will
show up on top of those that
come before them. The zorder also controls the order
of focus movement.
The palette shows some
important information about
each widget, to allow you to
identify them as you scan the
list. The first line of each entry
is the id (name) given to the
widget. Widget ids are
discussed in detail below, but
briefly each widget can be
given an id. Though it is
optional for most widgets, it
does though help identify
them more easily, even if the
id is not required for other
purposes. You can see the
most widget in the palette do
not have an id, and so it
displays [No Id].
The next line indicates the
position of the widget within
the parent template, and the
type of widget.
If any widgets are selected in
the editor window, they will be highlighted in the palette, as you can see two of them are here. And it works the other way as well, i.e. if
you select widgets in the palette, they will be selected in the editor window also. This is a convenient way to select widgets that might be
covered or hard to find visually. You can select multiple widgets by either holding down the Ctrl key and clicking (to select non-adjacent
widgets) or holding down the Shift key and clicking (to select all of the widget between the widget with the cursor and the new widget.)
The \ and / keys will select or deselect the whole list.
The action palette at the top allows you to do some operations via the widget palette. The palette items, from left to right, allow you to
invoke the attribute dialog of a single selected widget, to move a single selected widget forward or backwards in the z-order, and to
delete a widget. You can also double click on a widget to invoke its attributes dialog. Note that you cannot perform any actual editing
operations on the widgets via the palette; instead you have to go over to the editing window to do that.
When you move the mouse over a widget in the editor, the right side of the widget palette will show you more information about that
widget. The information displayed here changes based on what type of widget the mouse is over, but it gives you lots of information that
can be very useful, without having to open up the attributes dialog and dig through its attributes.
Grouped widgets will be indented to the right, under the first (lowest Z-order) member of the group, to make grouping visually evident.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 18
Hot Keys
For power users, the Interface Editor supports a set of hot keys that allow you to adjust widget attributes. Like the action palette above,
they affect all of the currently selected attributes, though if any of the selected widgets don’t make use of the attribute being modified,
those widgets will not be affected. The currently available hot keys are:
Hot Key
Description
Ctrl-A
Select all widgets
Ctrl-H
Invokes the search and replace dialog
Ctrl-N
Create a new (blank) template
Ctrl-O
Open a template
Ctrl-S
Save the current template back to disk
Ctrl-V
Paste widgets on clipboard at current mouse position
Ctrl-X
Cut the selected widgets to the clipboard
Ctrl-Z
Undo the last change
Ctrl-Alt-A
Save all currently opened templates
Ctrl-Alt-B
Toggle border attribute on and off
Ctrl-B
Toggle bold font attribute
Ctrl-Alt-C
Copy selected widgets to clipboard
Ctrl-Alt-H
Toggle the horizontal text justification attribute
Ctrl-Alt-I
Toggle the italic font attribute
Ctrl-Alt-S
Toggle the drop shadow attribute
Ctrl-Alt-T
Toggle the transparent background attribute
Ctrl-Alt-U
Toggle the underline attribute
Ctrl-Alt-V
Toggle the vertical text justification attribute
Ctrl-Alt-X
Cut the selected widgets to the clipboard
Ctrl-Alt-+
Increase the text font size
Ctrl-Alt--
Decrease the text font size
Ctrl-Shift-V
Del
Ctrl-[arrow]
Run a verification pass on the current template and report errors.
Delete the selected widgets
Up/Left will shrink the vertical/horizontal size of the selected widgets.
Down/Right will grow the vertical/horizontal size.
[arrow]
The un-shifted arrow keys will move the selected widgets in the selected
direction.
F7
If a single widget is selected, this will bring up the attributes dialog for that
widget.
PageUp/Dn
If a single widget is selected, this will move it up and down in the z-order.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 19
Widget Selection/Manipulation
As with most graphical/screen editors, you will primarily interact with the designer via the mouse. There are a number of ways to interact
with or select widgets. Selection is important because most operations target the currently selected widgets.







The simplest scheme is to just click on a widget. This will de-select anything else and select the clicked on widget
You can also lasso select by clicking and dragging. This will drag out a rectangle and any widgets that touch that rectangle will
be selected.
Sometimes a widget may be covered by something else. In that case you can click on the topmost widget, then hold down shift
and right click and the selection will move down through successive layers of widgets until it gets to the template. Then it will
move back to the original widget again. At any point, you can hit F7 to bring up the attributes dialog, move the widget with the
arrow keys, change its z-order with the page up/down keys, etc…
There is a Select All menu item to just let you select all widgets in the current template.
If you right click, then this will pop up the edit menu. If you do this on a currently selected widget, then that select remains and
the popup applies to the selected widgets. Else the widget hit (which might be the template itself) will be selected before the
menu is popped up.
If you left click on already selected widgets, they will remain selected and you can then drag them around. If you click on an
unselected one, then it replaces any previous selection and you can then drag it or just release to leave it selected.
You can Ctrl-Left click to add more widgets to the current set of selected widgets, or to remove one from the current selected set.
Image Management
As previously mentioned, CQC does come with some nice built in images. But you must upload any of your own images to CQC that
you want to use in your templates. To do this, you will use the "Image" menu item of the Interface Editor's main menu bar, and then
select the Manage item, and then the
Manage Images dropdown item. This will
present you with the image management
dialog, which looks like this example.
This dialog allows you to browse CQC's
'image repository' which lives on the master
server. It also allows you to upload images
to the repository for use in your user
interfaces. The repository is hierarchical
just like a hard drive, so it has 'directories'
that can be nested in whatever way you
want, and image files can be placed into
that hierarchy wherever you want. This
allows you to categorize image files so that
they are easier to locate when you want to
use them.
The repository is divided into two major
directories or scopes as they are sometimes called, one for user images and one for system images. You will put all of your images
under the \User part of the hierarchy. Any images that Charmed Quark ships with the product will go under the \System scope so that
there will never be any potential clashes of image names.
In the above example, we have navigated down into the \System\General\Icons\ scope. When you highlight an image, you will see a
preview of it to the right, so that you can know what image you are selecting. You can make new scopes (in the User area) at any time
using the rightmost button at the top of the dialog. The new scope will go under the currently displayed scope.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 20
When you invoke this dialog from the Images menu item, then you are in 'management mode', which means you are not selecting an
image to use, but you are just managing images
in the repository. The most common action is to
upload a new image. To do this, navigate to the
scope you want it to be in, and then enter the
name of the new image into the File Name field
and press the "New..." button. If that name
already exists in the current scope, you will be
asked if you want to overwrite it. You will then be
taken to another dialog just like the one above,
but it will allow you to navigate the local hard
drive to select an image to upload.
So navigate to the file you want to upload (BMP,
JPEG, and PNG files only at this time) and press
the Open button (or double click on the file) and
that image will be selected for upload and loaded
into the preview dialog. So for this example, I’ve
navigated over to the /User/ scope and entered
Button1 as the name, then pressed open to
import an image for that name. The import dialog
is presented here slightly reduced to fit better:
When you upload, you are given a chance to
modify the image in a few ways. You can scale
the image before importing it if you need to. This is a very high quality bi-cubic spline scaling, so the results will typically be very good.
Scaling images on the fly during viewing involves much higher overhead than using the correctly sized image to begin with. You can set
the ‘gamma’ curve of the image if needed. Most of the time you will not need to do this, but this allows you to adjust relationship
between the changes in the numeric sample values of each pixel and the change in brightness that occurs. It allows you to bring up
some darker details, but often at the expense of washing out brighter areas. And you can flip the image horizontally or vertically if
needed. Other transformations will be supported in the future. If the image is larger than the preview area, the scroll bars will allow you
to move around in it.
Most images use alpha based transparency, as the example does above. Note how you can see the checkerboard pattern through the
red halo around the button. But, some older images might use color based transparency. If so, the Transparency Options section will be
enabled. Check the Color Transparency check box, and then drag the little mouse over the image until it’s over the color you want to be
transparent.
When you are happy with the results, press the Done button to close the preview dialog and import the image. It will be uploaded to the
master server and you will be taken back to the management dialog, where the new image will now be visible:
You can also delete and rename images in the repository by right clicking on an image and selecting from a popup menu. Be careful
about renaming images if they are in use by user interfaces since the image name that they refer to will no longer exist and you’ll have
to go fix those references.
If you want to go back and edit an image in the repository, select it and press the Edit button. This will take you back to the preview
dialog where you can edit the image and then save it back.
Bulk Import
If you need to import a set of images, the one at a time scheme above can be a bit tedious. Another option is to cut and paste them into
the repository. Use Windows explorer browsing to find the images you want. Select and do Copy. You can then navigate within the
image repository (when in Manage mode, and under the \User section) to the location you want to import to. Put the focus on the file list
window and do Ctrl-V to paste the images. A dialog box will pop up, showing the progress of the import operation, indicating for each
image if it worked or failed. When it is complete, all the images that were successful will now be in the repository. In this scheme you
have no chance to edit them or change their names in the process of import. They will be named as their original files were named.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 21
Note that no hierarchy is maintained. If you do a Copy of images from multiple directories, they will all end up in the target scope.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 22
Template Management
The File menu item of the designer's main menu bar allows you to open, save, and create new templates. You can load existing templates
for editing, create new ones, save the template you are working on, or save one template to another name in order to create another
template exactly like it that you can then modify.
If you attempt to exit, or close the current template, and you have made any changes, you
will prompted to save the current changes before continuing with the requested operation.
You also do a Save All to save changes to any currently opened templates, instead of
saving them one by one.
You can also choose to invoke validation from this menu, though generally you’d do it via
the Ctrl-Shift-V hot key. This will invoke a validation pass on the template and show you
any errors. For each error displayed, just click on it and the editor will take you to the
attributes of the offending widget so that you can address the error indicated. This only
works on the currently active template window, if you have more than one template open
at the time.
editing it.
Once you select a template from the list, you will go back to the designer screen and the
selected template will be loaded for editing. The newly opened or created template will be
opened in a window that will be on top of any others, so that you can immediately start
When you use the Open… menu item, you will get the standard CQC file dialog where you can browse around and find the template that
you want to edit. As with images above, the templates are stored in a hierarchical arrangement, with two major sections. One is the
\System area which you cannot edit, and the \User area where you can put your own created templates.
Note that deletion and renaming of templates if not supported when you do File -> Open. To manage templates in the repository you must
use the Manage menu item. Under that menu you will see menu items to manage templates or images. You can browse around and
delete images/templates, or whole directory tress, and rename templates in place (as opposed to Save As above which keeps the original
and creates a new copy under a new name.)
The Save, Save As, and Validate options only work on the currently active template window (the one on top of all of the others.)
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 23
Search and Replace
Template widgets involve a lot of configuration data, and changing them when circumstances change, or when you want to reapply some
interface content to another situation, would be very tedious if you
had to do it by hand. The search and replace dialog allows you to
make these types of changes much more rapidly, though some
hand changes may still be required depending on circumstances.
If you have the template itself selected, then you can either just
affect the template, or you can affect the template and all
contained widgets. Just check the Search Child Widgets option to
make it search all child widgets when the template is selected.
Otherwise it only searches the selected widgets.
You can provide a regular expression or a literal value, and
choose replace any occurrence of the value or only if it fully
matches the target value from start to end.
You must select what types of data you want to have affected.
This is important since some types of data might also include the
term you are replacing but you may not want them affected.
If you check Action Parms, then the search and replace will also
be applied to any actions that are configured on the widgets being
affected.
and so forth.
Expressions affects the Boolean tabs (where you select true/false
state for things like check boxes, Boolean images, Boolean text
Note that you can select Field Name and Moniker. The latter applies to situations where only a device moniker is used, such as a media
repository associated with a cover art browser. Field Names include any of the regular field type associations. If you want to be sure to
affect just the device moniker part of such field names (which are in the standard Moniker.Field format), then end the value with a period,
e.g. “MyMoniker.” So it will only match that value when it ends with a period. You would then need to do potentially a separate pass where
you select just Moniker (get rid of the period) and replace just the moniker usages.
Text affects just the caption text of widgets. Var Name is similar to Field Name and will search any variables names for possible
replacements. You can limit the search by including the GVar: and LVar: prefixes in the search string.
Searching action parameters will include the actions in template level actions, and event driven actions defined on the template itself, not
just actions in the widgets. You can also have the event filter parameters of event driven actions be searched if you want.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 24
Actions in Templates
You’ve already been exposed to the configuration of actions elsewhere. But in the interface system, actions become even more powerful
because widgets can become the targets of commands. You can give any widgets a ‘widget id’, basically some meaningful name that is
unique among its siblings, and those named widgets will show up as targets in the action editing dialog. This ability makes CQC’s
interface system very powerful, because you begin to get some of the benefits of a user interface coded by hand, but without any of that
complexity.
All widgets support a small number of common commands, and then some widgets support type-specific commands that are meaningful
only for them. The type-specific commands are documented in the per-widget type documentation sections later on in this document. The
common commands are as follows:
GetWidgetColor(srcclr, format, tarvar)
This command will query one of the standard widget colors in on of a set of supported formats. It will put the result into the
named target variable. You can query it in RGB, HSV integral, or HSV floating point formats. The colors are actually
stored in RGB format but there are reasons you might want to query them as HSV.
SetWidgetState(State)
This command will cause the target widget to hide, show or disable itself. The State parameter is an enumerated value
and can be Hidden, Disabled, or Normal. Disabled only has any meaning for widgets that accept user interaction, and it
just prevents them from reacting to such interaction. For any other type of widget it will have no practical effect since they
already didn’t accept any user interaction.
SetWidgetColor(targetclr, clrtoset, format)
This command will change one of the colors of a widget. You will select the target color to set (one of the standard
colors), a new color value to set it to, and a color format. This will only have an effect if the widget uses the color you
changed. The format allows you to set the color in various RGB and HSV type schemes. You can set RGB, HSV in
floating point or integer form, only the HS part of HSV or only the V part of HSV.
The latter two are often convenient when working with a color palette widget and you want to provide a color preview
widget. The palette provides H and S, and you have to provide V separately, usually via a slider. This way you set the
separate parts of the color without having to get it out, parse out the bits you want and recombine them.
There are also some special case commands that you can send to the Interface Viewer itself, to do things that aren’t related to any
particular widget, or that affect whatever container (template or overlay) contains the invoking widget at viewing time. These are list below.
DismissBlanker()
If the blanker window is displayed, this command will dismiss it. This is typically only useful from an event handler
template action, since if the blanker window is up there’s no way the user is directly interacting with the template.
DoFades(true/false)
By default popups will fade in and out when they are opened or closed, over about half a second. This is attractive
visually and makes it easier for the user to follow what is happening. But, if you want to disable this, you can call this in
the OnPreload of the base template to disable it for all subsequent popup invocations.
Exit(result)
This command, when invoked from within a popup template, will cause that template to exit. Any commands after this in
the action will be ignored. Control will return to the action that invoked the popup. See the InvokePopup and
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 25
InvokePopout commands below. You pass a return result, which is a True or False value. This will become the return
value of the InokePopup/InvokePopout command, which makes it easy to show a popup and do something upon return or
not, depending on how the popup was exited.
If the user has a keyboard and presses Escape, the popup will exit with a False status.
GetRetVal(name, targetvar, mustexist)
GetTmplVal(name, targetvar, mustexist)
The base template (and any popups) can store values for their own use, called template values. These are separate from
variables and they live only as long as the base template or popup that creates them. They can be used to store info until
needed later, without having to ‘pollute’ the global variables space. They can also set values before they exit, which the
underlying (invoking) template can then get out. This also allows for returning values from a popup without having to use
global variables (and be sure they get cleaned up.)
GetRetVal is for the invoking popup to get return left for it by an invoked popup. GetTmplVal is for the base or popup
template to get template values it previously stored. These commands can either return a True/False value indicating
whether the value existed, or they can throw an error if the value doesn’t exist, depending on the value of the mustexist
command parameter.
InvokePopup(TemplateName, Parms, Origin)
InvokePopout(TemplateName, Direction, Origin, Parms)
These commands will cause a new template to open over the current one. This new template is ‘modal’ meaning that you
cannot interact with the underlying template until you have closed the new one. So they act much like standard Windows
dialog boxes in that sense. The difference between them is that one just pops up instantly, and the other slides out over
the course of a second or so (could be slower if you machine cannot keep up with the fairly substantial processing
requirements.) The TemplateName is the template you want to display in the popup.
The Origin parameter is a point that represents an offset from the top left corner of the template that invokes the popup, in
the form “x y”, so something like “10 20” would be 10 pixels over and 20 pixels down from the upper left of the calling
template. For a popup, you can use a value of “-1 -1” if you just want the new popup to be centered over the calling
template. Popouts must have a actual origin provided.
Popouts can pop out from the top down, left to right, right to left, or bottom up, according to the Direction parameter. For a
pop-out, the origin depends on the direction. From the left or top, the point is used as the upper left of the final position.
From the right the upper right is the upper right of the final position. From the bottom, the lower right is the lower right of
the final position. The easiest way to set the origins is to right click at the point you want to use and select the Copy Point
menu item. This will put the point coordinates onto the clipboard and you can then just paste them into the Origin
parameter.
You can pass parameter to a popup/popout. These are passed as a quoted comma list, of the sort that is used in various
places throughout CQC. These will show up as special local variables that the popup can access and react to. They are
named LVar:CQCActParm_1 through LVar:CQCActParm_X, and the numbering is based on the order that they are
passed. These will be available to any action run within the popup.
Note that these can be invoked as conditional commands or non-conditional. Popups are exite by some user invoked
action calling the Exit() command, see above. That command takes a True/False value, which becomes the return value
of this command that invoked it. This makes it easy to have popups presented to the user, where they can choose to do
something or not, and the popup indicates which choice was made by calling Exit() with the appropriate return value.
Also note that, if you click the parameter value helper button for the Parms parameter, and you have selected a valid
template in the TemplateName parameter, it will pop up a small dialog box that shows the notes of the target template. So
you can document the parameters, variables, template values, return value, etc… that a popup requires in the popup’s
notes and get a reminder of what is required via the value helper button.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 26
LoadAncestor(template, target)
This command will get mapped to the main template or overlay that contains the invoking widget. It allows you to load a
new template into a grandparent, great grandparent, etc… container, which is sometimes desirable. It doesn’t support
loading the parent of the invoking widget, since just calling LoadNewTemplate() will achieve that.
It must be the last command in the action, since it is going to destroy the invoking widget and all of the containers up to
(but not including) the one that it targets, so any commands after this one are ignored.
Note that this only applies to the current level, i.e. base template or popup. You can’t reload the base template from a
popup. So it’s only direct ancestor containers.
LoadNewTemplate(template)
This command will react in two different ways according to where it is invoked from. If it is invoked by a widget in the main
template or a popup, it will load a new main template or a new template into the popup. If it is invoked by a widget in an
overlay, it will load a new template into the overlay.
LoadDefTemplate()
This command will load the default template that is configured for the currently logged in CQC user. It only works when
invoked by a widget that is a direct child of the main template, i.e. when no popups are displayed.
LoadSiblingOverlay(template, target)
This is a special case command, which allows a widget in one overlay to cause another overlay to load a new template.
This command is somewhat of a misnomer now since it was hijacked to also allow you to force other overlays besides
those that are strictly siblings of the overlay that contains the invoking widget. The basic use of it for an actual sibling
works like this: If a template has overlays A and B, then a widget within A can force B to reload by just giving the name of
B as the target.
However, you can also use a path-like target indicator to target other overlays. If A contains a D overlay, then a widget
within B could target it by this path “..\\A\\D”. The .. double dot notation means move upwards a step, where A lives, then
go downwards to D. If A contained a nested overlay named X, into which a template was loaded that contained a Z
overlay, then a widget within A could use a path like “.\\X\\Z” to target that overlay and make it reload.
You cannot use LoadSibling overlay to reload an ancestor of the calling widget, i.e. in such a way as it would destroy the
widget that invoked the command. Use the LoadAncestor command for that. This restriction means that this command
does not have to be the last command in the action, as LoadAncestor does.
If target uses a relative path, then it is relative to the original template that invoked the command. So, in the ‘widget in A
forces B to reload’ scenario, it would be relative to the template loaded into A, not the one loaded into the target B.
NoChildMouse()
This is a pretty specialized one and not often used. In some cases, if you use the Web Browser widget to embed a web
page into your templates, and it loads some type of ActiveX, on occasion if that ActiveX sees mouse/pointer activity it will
have problems. This will cause those to be suppressed.
RetValToTmplVal(retvalname,tmplvalname)
See GetRetVal/GetTmplVal above for more info. This is a convenience for invoking templates, to get a return value out
and into a template value in one step, instead of having to use an intervening local variable.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 27
RIVACmd(cmd, parm1, parm2, parm3)
This command allows you to send arbitrary commands to RIVA clients. Each RIVA client implementation can define one
or more such commands that they will respond to. What the command name and parameter values are is completely up
to the RIVA clients.
ScrollParent(dir,target)
This command allows a widget to cause some containing overlay to scroll left or right. The direction is Left or Right, and
the target indicates the parent, grand-parent, etc… And also ‘Root’ means the top level containing overlay. So this is
targeted towards the Intf.Viewer target, but it gets eventually to some up-stream container to process. This is done
asynchronously, i.e. the request is posted and the action continues. When it is complete, then the posted gets back in and
the target is found and asked to scroll.
SetAutoBlankMode(Mode)
This command will set the auto-blanker mode, which controls how the blanker reacts when the auto-blank period expires.
The mode value is one of the values: Blanker, Blank/Blanker, ClockBlanker, and ShowBlanker. The first will put up the
blanker window. The second will put up the window and turn off the display if that is possible on the local hardware. The
third will put up the blanker window and it will display a screen saver type clock display. The fourth will allow you to use
the blacker as a picture frame. See the Interface Viewer Guide for details.
SetBlankOpts(Milliseconds, PUTemplate, PUParms)
This command will set the auto-blanker timeout period, in milliseconds. Setting zero will disable auto-timeout. Anything
else will cause the Interface Viewer to invoke the blanker after that many milliseconds of inactivity.
You can invoke a ‘secure mode’ by providing the path to a template. When the blanker is dismissed this template will be
run as a popup. The third parameter allows you to pass parameters to the template, and must be in the form of a quoted
comma list. The template can refuse to exit until the user provides some sort of password or other identifier, effectively
providing a security mode in which the user must re-verify his right to access the system after it blanks.
SetRetVal(name, value)
SetTmplVal(name, value)
These are the setter versions of the GetRetVal/GetTmplVal commands defined above. So they allow a popup (or base
template) to store template values, or for a popup to set return values for the invoking template to see after the popup
exits.
TmplValToRetVal(retvalname,tmplvalname)
See GetRetVal/GetTmplVal above for more info. This is a convenience for invoke popups to move values it has stored in
its template values over into return values for the invoking template to see, without having to use an intervening local
variable to do it.
More standard commands will be added over time, but there will generally be more widget-specific commands, because that’s where the
real power comes into play.
¹ These commands will not return until the popup exits, at which time any subsequent commands in the invoking action will begin to execute. So you
can use popups to get information that is returned in global variables or template return values, which your action then react to. This is a very powerful
capability.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 28
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 29
Widget Types
This section will describe the available widget types, and we’ll add some to a scratch pad interface template to visually show you the
results of changing the various widget attributes. To begin the discussion, here is a list of the types of template widgets that are
supported by the interface system at this time. Other types will be added over time, but the current set allows for some quite elaborate and
powerful interface designs.
Note that many of these have multiple variations. Any widget that changes itself to reflect some value will generally have one variation that
can be associated with a device field, one variation that can be associated with a global variable, and often a ‘static’ version which just
allow you to manage a value internally within it, usually be sending it commands.
















Animated Image. Supports simple animation needs, so that you can do things like display a rotating fan if a fan is on and so
forth. It is associated with a field and when that field is evaluated as true, it will cycle through the images you assign to it, one per
500ms.
Area Color Fill. Area fills just do a simple fill of an area with a flat color field, or with one of the support gradient type fills and
optional border.
Boolean Image. Boolean images display one of two configured images, depending on the result of a evaluating the value of an
associated field or variable. There is no static version of this one, just use a static image for that.
Boolean Text. Boolean text widgets display one of two configured text values, depending on the result of a evaluating the value
of an associated field or variable. There is no static version of this one, just use a static image for that.
Calendar. A standard type of calendar display, which you can send commands to I order to make it scroll through years and
months. The current day can be highlighted by color and/or image.
Check Box. Check boxes provide functionality similar to check boxes and radio buttons in the Windows GUI. It is associated
with a field or variable, and there is a static version that just maintains an internal true/false value. It displays true/false text and
images based on the true/false state of its evaluation statements, and can invoke True of False actions based on its current state
when clicked on.
Cmd Button. Action buttons invoke an action which you configure for the button. This is the primary means by which you allow
users to cause things to happen. There is a static version (fixed text) and variable/field based ones that get their display text from
a variable of field, respectively.
Color Palette. This is primarily for supporting colored lighting systems like the Hue, but you can use to select colors for any
purpose of your own.
Cover Art Browser. A media oriented widget that allows you to browse the media (by cover art) in a media repository. It is
usually configured to invoke a renderer when you click on one of the cover art items, so that that renderer will start playing the
selected title. This is often done indirectly, first displaying preview information, and then allowing the user to elect to play or go
back to browsing.
Digital Clock. Digital Clocks display a digital clock widget, the display style of which you can control. It shows the local time on
the machine the template is loaded on. There is also the Time/Date Text widget below, which is similar but just displays the text.
Digital VU Meter. VU meters present a standard digital VU meter, composed of a set of green, yellow, and red LEDs.
Associated with a numeric field or variable of limited range, and shows its current value. You can configure where in the range
the LED colors fall. There is also a static version that just maintains an internal value you can set via commands.
Driver Image. This widget uses a standard backdoor command that any driver can implement, to download image data from the
driver, which this widget will display. So it’s an open ended way for drivers to serve up images for display purposes.
Enumerated Image. Enumerated images are associated with an enumerated string field for variable that has an enumerated
limit. You can associate an image with each of the enumerated values, and it will show the image for the field's current value.
Graph. Graph widgets can be associated with graph ‘fields’ defined I the Logic Server. They will display the graph data in the
fairly standard right to left scrolling manner.
List Browser. These can be associated with a ‘string list’ field in a device, and there is a static one that you can just set a list of
values on locally. It will display the values of that list in a scrollable horizontal or vertical list, and allow you to react to a user
clicking on one of them. You can associate some user data with each of the values as well, which is not displayed but allows you
to react to something besides the displayed text to decide what to do when an item is clicked.
Line. Draws horizontal or vertical lines, with the option for a couple line end styles.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 30


















Live Tile. This widget type supports a fairly common modern display scheme, which involves ‘tiles’. In CQC world these are
effectively non-interactive overlays (see Overlays below) combined with buttons. They can display information and act like a
button when clicked to make something happen.
Logo Image. This widget is a specialized image widget which is commonly (but not always) used when displaying things like
channel logos. It is associated with a field, and a scope in the CQC image repository, and if the field has the value 10, for
instance, it looks for an image with the name 10 in the associated scope and displays it. So it is often used to display channel
logos, such as DirecTV or XM Radio logos, by associating with a current channel field.
Mapped Image. Mapped images are similar to an enumerated image, but not limited to enumerated fields and variables. It
allows you to set up an arbitrary set of images, and an expression for each one that is used to decide which one should be
displayed. The value of the associated field or variable is used to select the image to display, or none if the value matches no
image.
Marquee. These will display the value of any variable or field in a scrolling line. There is also a static version that takes a fixed
piece of text to scroll, though you can send it commands to change the text if you want. If the text will display fully within the
widget area, it doesn’t scroll. Else it slowly scrolls it across the widget area from right to left.
Media Category Browser. A media oriented widget that allows you to browse the categories available from a media repository.
When clicked, it normally is configured to send a command to a cover art browser to make that browser start browsing the
clicked category.
Media List Browser. This is similar to the Cover Art Browser above, but it is a text list based media browser, instead of working
via cover art. It is similar in concept to the iPod style browser, with a set of nested lists that replace each other as you make
selections.
Media Image/Media Repo Image. These are used to display the cover art of the, respectively, item currently playing in a
renderer driver or a collection or title set from an associated media repository driver. The latter is for media preview screens. You
send it a collection or title set cookie and it will pull down the image from its associated media repository.
Media Item Browser. A specialized vertical list browser that allows you to see the list of items currently being played by a media
renderer driver, as opposed to preview of items before playing, which is done by the Media Repo Item Browser below. Clicking
on an item invokes an event that you can react to do various things such as make that the active playing item.
Media Item Browser (Advanced). This is a more powerful version of the Media Item Browser. In this one, you can define the
appearance of list slots by creating a ‘layout template’, which is a separate template that tells the browser what information to
display about each item in the list.
Media Repo Item Browser. A specialized vertical list browser that allows you to see the list of items associated with a collection.
These are used for previewing track information generally, as opposed to the Media Item Browser above that shows what is
already playing in a renderer.) Clicking on an item invokes an event that you can use for things like displaying item metadata or
queuing up the item in a player’s current play-list.
Media Repo Text. Displays a selected metadata field from an associated media repository driver, used in media preview
screens mostly. For viewing live metadata from a player, just use a Dynamic Text widget.
Numeric Text. Dynamic numeric text widgets display the textual value of an associated CQC device field, but only support
numeric values and provide a lot of options to control the formatting of the numeric values.
Overlay. Overlays are named objects which are targeted by action that load another template into the area of the overlay.
Generally a set of buttons in the main template will load different templates into a common overlay area.
Progress Bar. Used to graphically display the value of a numerical field or value relative to the low/high values its value is
limited to. Commonly used to show current song playback progress, temperatures, levels and so forth.
Slider. Used to display and/or set the value of a numerical field, such as volumes, light levels, temperatures, and so forth. For
read only fields, it’s just for display. For writeable fields or for variables it will set the value as well. There is also a static version
that just maintains an internal value for local use.
Special Action Button. Special action buttons are specialized buttons that allows you to do some special types of actions like
exit the interface and invoke the blanker window.
Static Image. Static images display a static image, usually for decorative or labeling purposes but you can send it commands to
display a different image, so it can be used as a status display in some cases as well.
Text. Text widgets either display the current value of an associated field or variable, or they take a static piece of text to display
usually for labeling purposes. The static version can be updated via commands sent to it at viewing time. There are specialized
text display widgets, such as the date/time or numeric text widgets. These cover all the non-specialized scenarios.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 31






Time/Date Text. Used to format out Time stamps in various ways. So it’s a specialized form of a dynamic text widget. There is
one version for time based fields, and another that gets its value from the local system time.
Time Image. This widget is primarily intended to create clocks, being able to drive two separate images based on a numeric
field, but could be used in various other ways.
ToolBar. A specialized horizontal browser widget that allows you to scroll through a list of buttons, each of which can invoke an
action. Each button can have text and/or an image.
Volume Knob. Volume knobs provide a standard rotating volume knob, much as you would find on many A/V devices, allowing
you to adjust a numeric ranged based field or variable, often a volume field but not necessarily. There is also a static version that
just maintains an internal value for local use.
Weather Channel. A specialized mapped image that understands the ‘conditions’ fields of the weather channel driver. It
understands what images to display for each possible condition code. You could theoretically do this yourself with a mapped
image, but it would be very tedious and less efficient.
Web Browser. Allows you to embed a web browser into your interfaces. It accepts commands for standard web navigation and
to set a new URL.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 32
Configuring Widgets
The first thing you will do to a new widget after creating it, moving it where you want it, and sizing it to whatever size you need, is to
modify its attributes. There are a few ways to adjust the attributes of a widget.



The action palette
Hot keys
The attributes dialog
Action Palette
The action palette was seen in the initial image of the Interface Editor above. It is the palette of small images and text in each of the editor
windows.
This palette allows you to do the following things, in order from left to right::











Left align the selected widgets, to the left edge of the first item selected
Right align the selected widgets, to the right edge of the first item selected
Top align the selected widgets, to the top edge of the first item selected
Bottom align the selected widgets, to the bottom edge of the first item selected
Move the selected widgets such that their horizontal center points all are aligned on the center point of the first selected widget,
i.e. move them horizontally to get them all aligned in a vertical row.
Move the selected widgets such that their vertical center points all are aligned on the center point of the first selected widget, i.e.
move them vertically to get them all aligned in a horizontal row.
Distribute the selected widgets such that their horizontal center points are distributed evenly between the left-most and right-most
selected widget’s center points. The rightmost one may be moved slightly to get an even distribution.
Distribute the selected widgets such that their vertical center points are distributed evenly between the topmost and bottom-most
selected widget’s center points. The bottom one may be moved slightly to get an even distribution.
The next five allow you to directly set the available colors for all of the currently selected widgets. If any selected widgets don’t
use the particular color changed, this will have no effect on those widgets.
The next item allows you to set the font on all of the currently selected widgets. If any selected widgets don’t display any text, this
will have no effect on those widgets.
The next two items allow you to set the italic and bold font attributes on all of the currently selected widgets. If any selected
widgets don’t display any text, this will have no effect on those widgets.
You can use the alignment buttons in combinations to achieve particular effects. For instance, to right align some buttons down the right
side of the template, evenly distributed vertically, place the first and last ones where you want them vertically, then select the mall, click
the vertical distribution button to distribute them between the first and last widget vertically, then use the right lighten button to right align
them, then drag them to where you want them o the right edge of the template.
If you can’t remember what a particular item does, just hold the mouse over the item and a ‘flyover’ window will pop up describing what
that item does.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 33
Attribute Tabs
A third way to adjust widget attributes is via a tabbed dialog that presents all of the available attributes for the selected widget type. We
added a static text widget above, which has a number of very common attribute tabs, so right click on the new text widget and select the
Attributes menu item to get the attributes dialog (or you can just double click on the widget.) The attributes dialog only affects a single
widget at a time, but provides access to all of the widget’s attributes.
Note that the dialog box will come back up wherever you last positioned it, so you usually want to move it away from the widget you are
working on. This way, you can see the changes occur as you make them, since all changes are immediately taken. If you make a mistake,
you can use the Revert button to take the widget back to the state it had when you first popped up the dialog box.
The various attribute tabs will be discussed in detail in the subsequent sections of this document.
Common Attribute Tabs
There are a number of attribute tabs that are re-used widely among the various widget types. One is present in every type of widget.
These common tabs will be described first, and then later on in the documentation of specific widgets, only the tabs that are specific to
those widget types will need to be discussed. The screen caps are reduced in size here to reduce the size of the document.
Note that in some cases any widget that implements a particular common tab also will accept commands that affect those characteristics
of the widget that pertain to that common tab. If so, it will be commented on here in the common tabs section and not repeated over and
over in all of the individual widget type discussions later.
Text Tab
The Text tab is pretty straightforward. If a widget has any text associated with it, it will get a text tab to allow you to set the text. As the
instructions indicate, you just need to type in the text
you want the widget to have, and you will see the text
widget change as you type the text. You can use
tabs and new lines to create multiple lines of
formatted text.
Some widgets don't allow multiple lines, and they use
a different tab to get their more specialized text. But
most allow for formatted text via the Text tab. You
can enter multiple lines if desired.
Some widgets will allow you to put special
replacement parameters in the text, or will apply other
special characteristics to the text, so check the widget
specific documentation.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 34
Font Tab
If a widget has any associated text, its attributes dialog will have a font tab. This tab allows you to select the font face name, the font
size, the bold and italic attributes, and the justification of
the text within the widget area.
As with the text tab, you will see the changes happen as
you make them, and you will also see them show up in
the sample area in the lower left of the Font tab. The size
is in terms of pixels as are the sizes of the widgets. So
the size that you set here will remain the same relative to
the widget size when displayed on various displays. The
Bold/Italic settings are self explanatory.
The No Text Wrap setting will prevent the widget from
wrapping the
text to
multiple lines
if it is longer
than the
widget has
room to
display.
Instead it will just clip if too long. So if you want the text to fit into a single line slot in a
background image, you will usually want it to just clip if too long instead of wrapping.
If you want to change the font face name, use the font folder button, and you will see the
font selection dialog. The fonts offered will be those available on the local machine. Be
careful about selecting esoteric fonts, unless you make sure that they are installed on the
other machines in your network, or some other font will be selected automatically. It will be
as similar as possible to what you originally selected, but might provide a much different
visual effect.
So, let's increase the font size a bit, and select a new font and right justify it, and the widget
should now look something like this. You may have to size the widget up a bit to keep it from
clipping the new text. Here the text has become larger, and it is now right justified in its
widget's area, and the font face has changed.
You can also select from a set of available special font effects, which can add tremendously
to the ‘eye candy quotient’ of an interface, though they do come at a cost in overhead. Select
a new Text color, which will make the text change to that color, then on the Font tab, in the
Effect section, select from the drop down list Gradient.. This will use background colors as
gradient fill colors and will fill the text with that gradient. So it might look something like to the
right.
You can also do reflections, which draws a fading version of the text upside downwards underneath the original text. You will usually
want to top justify the text when you do a reflection, so that you can see the reflection
while keeping the widget no taller than it needs to be.
You can also do blurs and drop shadows. Note that these are quite CPU intensive. So
you probably don’t want to do them on too many widgets, and the larger the text the
more overhead is involved. So use them carefully. For static text, where possible, you
might want to just pre-draw an image with the blurred text or drop shadow in it and use
that instead, and save the text effect stuff for dynamically changing text where you
cannot know ahead of time what the values will be, or where there are a lot of values.
But use your discretion and just see how it works for you.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 35
If the Interface Editor or viewer starts getting really jerky when you move windows over it or try to size it, then that’s probably the issue.
Watch the Task Manager’s CPU graph while you do it and see what kind of CPU usage is happening as these blurs are redrawing. We
will improve the performance of these graphical text effects in a subsequent release, though at the
cost of more memory, by drawing them only when they change and caching an image to display
when needed.
Note that only the Text colors are used by the effects, not the colors that might otherwise be used
by a particular text widget. Also note that some settings in the Basic tab, such as underline, drop
shadow, are overridden when an effect is selected. Fill styles are still honored, as is the transparent
background setting.
Just as an example of a use of the gradient text effect, which is more than just decorative, would be
in a situation like the one to the left. Here a button has a top glare effect, and the text has been set
to a gradient so that the top of the text seems to be affected by the glare as well. It’s subtle but
really helps to sell the realism of the glare effect. You could of course draw the text graphically as
separate images in order to get this effect, but it would be much more work to do it that way, and you couldn’t do that for more arbitrary
text that might be coming from a device field.
The reflection effect is very useful for creating a glossy surface effect. A simple gradient fill area will look very uninteresting. But put
some reflected text or graphics on it and it suddenly takes on the appearance of a glossy surface.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 36
Action Tab
A number of widgets allow you to invoke a single action, unconditionally. There are others that invoke this or that action based on
circumstances, but most just invoke one action when they are clicked. These all use the Action tab.
Click the Edit… button to edit the action. You will then
get the standard action configuration dialog that you
will have seen many times already by now. Configure
the action and save it. You will then see the details of
the action show up in the list area above the Edit
button.
Some widgets require an action to be useful, and for
some it is optional. If you don’t configure it, and it is
required, you will be warned about this later when
you try to save the changes.
Actions are discussed in detail elsewhere, in the
tutorial videos and in the Action Guide technical
document, so the action editing process is not
discussed here.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 37
Basic Tab
The Basic Tab contains the most fundamental attributes that are generally used by all widgets, though some of the attributes provided
here might not be used by every single widget. In the example below, the widget we are configuring does not support some of the
options, so those options are
disabled.
This tab allows you to set foreground
and background colors, control
whether the widget has a
transparent background or not,
whether it has a border, and whether
it should support drop shadow,
underline, etc…
A fixed set of colors are provided,
but they will be given names
depending on their usage by the
actual widget type being edited.
Those not used by the current
widget will be [N/A], not applicable.
All widgets will support theBgn Fill 1
and 2 colors, since all widgets can
have a background fill. If you select
the ‘Fill with bgn color’ option, then
the first background color is used to
do a uniform fill. For the other
options, both colors are used to
create various types of gradient fills. The other colors are used for things like text, borders, fills, drop shadows and so forth. The
documentation on each widget type will discuss how it uses the colors. So, let’s set all the colors to something different just to see what
happens. To set a color, double click on the color in the list, and you will see the color palette dialog box, which lets you pick a color.
Click in the color palette area to select hue, then select the saturation level with the slider to the right.
Note that, in addition to creating a color yourself, you can put the mouse on the tiny mouse icon in the palette window, and drag it
around to select a color from some existing visible screen content. As you drag the selector around, you will see the palette window
update to show the color you've selected. When you have the desired color, release the
mouse.
If you set each of the colors, check the border attribute,
and select the vertical gradient fill style, your widget will
look something like the example to the left. Play around
with these settings all you want and see how they all
interoperate.
You can mark a widget as “Initially invisible”. This will cause it to be invisible until you send it a
command to show itself, which is often useful. So, as this implies, this is just providing an initial
setting for the same visibility state that the SetWidgetState command controls. Note that this is a
separate setting from the State driven visibility setting. If this main visibility setting is set to hide,
then a state will not cause it to appear. The state visibility stuff only works when this main visibility
state is set to true.
Inertial scrolling can be disabled on a per-widget basis if you wish to do so. Normally this option
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 38
would not be selected but there may be some special cases where you want to do the old style instant page change instead of the
sliding inertial scrolling effect. This obviously only applies to those widgets that are scrollable.
The Base tab also allows you to give a widget an id. Widgets can be the targets of commands, but in order to be available as a target,
they have to have a name. So provide a meaningful name for those you are going to want to send commands to. These only have to be
unique within the parent template at design time, i.e. don’t worry about the other templates that might get loaded into overlays at viewing
time. Each nested level is a separate ‘namespace’.
If a widget is the first member of a group, then the Grp Name entry field will be enabled and you will be able to provide a name for the
group as well. This is just for visual reference. Any time the mouse is over a member of a group, the attribute summary in the widget
palette will show the group name.
You can also round the corners of background filled (non-transparent) widgets, using the Rounding option. You can control how much
rounding is applied. This is sometimes useful to create a desired effect.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 39
Values Tab
One less common, but still common, piece of functionality that a few widgets share is the ability to evaluate the value of an associated
field or variable, and decide whether the field or variable
value (hereafter called the source value) meets some criteria
or not. The widget will then use that true or false result to
display some information, though what gets displayed
depends on the specific type of widget. The Values tab
allows you to select from a set of expressions, which make
some test of the field value.
The expressions are visible above in the dropped down list
for the true expression. Some, like IsEqual, compare the
field to the value you enter (to the right of the selected
expression), and others, like IsNegative, just operate on the
source value itself and you don't have to enter any value.
One of the expression types is a regular expression, which
allows you to do more complex lexical comparisons. You will
be told if you select an expression that requires some
comparison text and you haven't entered any.
Here is a table that indicates what each expression type requires.
Expression
Requirements
Regular Expr
A regular expression string must be provided. The source value is formatted to text and
tested against the expression.
IsEqual/NotEqual
You must provide a text value to compare against. The expression is true if the source
value matches the entered value, or for NotEqual if it does not match. An attempt is
made to convert the comparison value to the target field's type and then compared.
IsTrue/IsFalse
Compares the field value to True or False. So it must be a Boolean source, or a numeric
or string. If numeric or time sources, non-zero means true and zero means false. If a
string, it looks for the values True and False, or 1 and 0.
IsGtThan/IsGtThanEq
IsLsThan/IsLsThanEq
You must provide a text values, and it is compared against the source value. An attempt
will be made to convert the entered value to the type of the source, and the comparison
done. The result is true if the source value and the comparison value have the indicated
relationship. If the source is text, then the comparison is a lexical comparison of the text
values, which can differ depending on locale.
NonNull
Check that the value of the source is either not empty, or if a numeric type that its value
is non-zero.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 40
IsNegative/IsPositive
Checks that the value of the source is positive or negative. For a Boolean source true is
considered positive and False negative. For numeric sources the sign of the value is
checked. For other field types they will always return false.
IsEven/IsOdd
If the source value is a number you can check if it is an even or odd number
IsMultipleOf
If the source value is a number you can check to see if it is a multiple of some other
number.
IsAlpha/IsAlphaNum
Checks to see if the source value is made up purely of characters (no numbers, no
punctuation), or of characters plus numbers (no punctuation.) A space character is
considered legal in either case. A floating point value would not pass in either case,
since it will have a period in it. An Int type source would pass for AlphaNum if not
negative, else it would have a negative sign. String type fields will just be checked to
see what they contain. Time fields will pass AlphaNum since they are just numbers in
their raw state.
You only have to provide one of the expressions. If you only provide the true expression, and it matches, then the result is true, else
false. If you only provide the false expression, and it matches, then the result is false, else true. If you provide both, then the true
expression is checked first, and if it matches, the result is true, else the false is checked and if the result is true, the result is false. If both
are provided, and both would match some given value, i.e. they are ambiguous, true wins because it is checked first. If you provide both
and neither matches, then the widget will go into error state because it doesn’t know what to do.

If you are dealing with a time based field or variable as the source, then the comparison value is assumed to be hexadecimal
format! So if you pass in 10, it will interpret that as 0x10, i.e. 16 decimal, which might not be what you want. So be careful to
provide hex values.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 41
Field Tab
A number of widget types are associated with a device field, and either display the value of that field, use the value of that field to
display some image or change their appearance, or allow you to modify that field's value.
You will be shown a list of the available drivers, and a list of
the fields available in the selected driver. The list will be
trimmed to show you the fields appropriate for the type of
widget you are editing. So if the widget sets a field's value,
you will only see writeable fields. If it requires a string list,
you will only see string list fields, and so forth.
You can also indicate whether writeable fields can be written
to directly. If you check the "Allow Direct Writes" check box,
and the field is writeable, the user will be able to double click
on the field when viewing the template, and set the value
directly. If you enable direct writes, you can indicate the
minimum user role required in order to be able to do it. If the
field is not writeable, this setting is ignored. Some widgets
provide more specialized ways of setting the value directly,
and their documentation will indicate so where applicable.
This just allows a backdoor to set the value of an associated
field even when the widget is just for display purposes
normally, mostly intended for administrators.
Note that you can change the field associated with a widget, at viewing time, by sending a LinkToField command to the widget. This
would normally be done in an OnPreload action associated with the template (which is run after the template is set up, but before it is
initialized) based on the value of one or more global variables which have been previously set. This is commonly done in order to adapt
a single template to multiple audio zones or multiple instances of devices of the same sort. You can also use LinkToField at other times
if you want, though normally it’s done while loading a template since the template is often being loaded in response to a button press to
view this or that device.
LinkToField is available on any widget that uses the Field tab, so it is not discussed separately in each individual widget below.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 42
Image Tab
Some widget types display a single, static image. The template widget can display a background image, the static image widget exists
purely to display a single static
image, the volume knob can show a
background image for the knob body,
and so forth. All of these use the
Image tab, which allows you to select
a single image and control its
placement and constant opacity.
If the image is optional, there will be
a “Use an image” check box to
indicate whether you want to use an
image or not. Click the preview
button (bottom left) to select an
image. This will display the image
browsing dialog, which we saw
before in the image management
section, but in this case it will be in
image selection mode, not
management mode. You can select
an image and it will then show up in
the preview button.
You can control the placement of the
image using the Image Options radio
buttons. And you can add constant opacity, i.e. make the whole image more or less transparent, using the Transparency Options slider.
All the way to the right is fully opaque.
The “Keep Aspect Ratio” and “Size to Aspect Ratio” options both will maintain the shape of the image. The difference between them is
that the latter will always size the image to fit, i.e. if it is bigger or smaller than the display area, it will be sized to fit the image best while
maintaining the aspect ratio. The former will only change the size if the image is too big. If the image will fit, it will be displayed at its
natural aspect ratio and not scaled up to fill the area.
There are some cases where you want to put an image over some interactive widget, for instance to provide a glare effect and the
widget itself doesn’t inherently support some sort of overlaid type of image. In those cases, you have an issue because clicks won’t pass
through the image to get to the interactive underlying widget. The “Transparent to touch” option allows you to make the image
transparent to clicks so that this will work.


The checkerboard pattern in the preview button isn’t part of the image. It is there to let you see for sure where the image ends
and, when the image supports transparency, and it allows you to see exactly were the transparent sections are.
Also note that opacity might be disabled for some widgets.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 43
Images Tab
Whereas the Image tab above is for widgets that display a single image, the Images tab is for widgets that display one of a set of
images based on their state.
Each type of widget will present you with a list of
named images that it supports. For the push button
style widget of the example here, they allow one
image for the un-pressed state, one for the pressed
state, one for when the button has focus, and
possibly another image that can be overlaid over
whatever other image is selected. A star beside an
image indicates it is enabled. You can double click an
image to enable or disable it, or if you press the
preview button to select an image, it will be
automatically enabled since you are selecting an
image.
As with single images, you can adjust the overall
opacity. But you cannot control the placement. Multiimage widgets always display their images in their
natural size, and will be centered unless you adjust
their position. By default the ‘offset’ values are at
zero, which leaves the image centered in the widget.
But you can adjust each of the images horizontally
and vertically if you choose to.
Sometimes images have interrelationships, so that if you enable one, others will enable and vice versa. Sometimes they are all required
and you cannot disable any of them, and sometimes they are all optional. See the documentation for the specific widget for details.
It is also possible that the list of images can change according to the configuration of the widget. For instance, the Enumerated Image
lets you select an image for each possible value of the associated field, so the list of images will change as you select different fields.
See the section on Navigation near the top of this document for an explanation of focus and why you might want to use the focus image.
Most widgets that use the States tab will support the SetNamedImage command, which allows you to change the image associated with
any of the enabled named images. Since all widgets that support this tab support this command, it is not repeated for every widget
below that implements it.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 44
States Tab
The States tab is available in most widgets. It allows you to associate the widget with one or more of the parent template's states, and
indicate what to do if the states match. First let's discuss how you create states. If you pop up the menu for the main template, one of
the options will be "Define States", which will invoke the Define States dialog box. It looks like this:
This dialog allows you to add new states to the template, or edit or delete existing states. You can also negate the result of the state.
Each state is composed of one or more expressions, of the sort discussed above in the Values Tab. Use the Add New button to add a
new state (you will be asked to provide a name and description of the new state), or Edit to edit an existing state. In both cases you see
the edit state dialog:
Here you can add new expressions to the state or edit existing expressions. Each expression has a true or false result, and all of the
expressions that make up a state are combined using the Logical Operation indicated at the bottom of this dialog box. If all of those
results, so combined, result in a true state, then the state has a true result. Here again, you can negate the result of any of the
expressions, so that its result will be negated before being combined with the other expression values. If you add or edit an expression,
you will get the Edit Expression dialog, which looks like this:
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 45
Here you will select a desired field that you want the expression to evaluate the value of, then provide a description of the expression,
an expression state, and if applicable a compare value to be used in the evaluation. Again, see the Value Tab section above for a
description of expressions. In this case, the InputNum field of a video switcher driver has been selected, a description has been added,
and the expression of IsEqual selected and a value of 1 is the value to compare the field against. Press save to go back to the main
expression dialog and you will see this new expression there. Save again to save this overall state and it will show up in the states list.
You can define other states if you want. When you are done, press Save and these states will be saved with the Template and they can
now be referenced in the States tab of any widgets of this interface. So let’s now go to the States tab for a widget, to see what is there:
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 46
Here you can see that the new state is available. You can now select a state and use the Add and Remove buttons to add a state to the
set of states this widget looks at, or remove them. When you add one, a check will show up beside it to indicate it is selected. In this
case, the “Hide if states match” checkbox has been checked, so this widget will be hidden if the DVDSrcSelected state becomes true.
We could also choose to disable it, which is sometimes approach for action type widgets where you want them to still be visible, but not
be clickable.
The Negate check box allows you to negate the result of the state. I.e. have this state affect this widget if the state comes out false,
instead of the normal true. This is very useful because you might have a set of widgets where one set should be available in one state
and another set in the opposite state. Without the Negate option you would have to create two separate states that generated the
opposite result. This way you can use one state for both scenarios.
If you select more than one state for a widget, then the “True If” setting allows you to control how to combine the results of the selected
states. You can have it affect the widget if all of them are true, if any one of them is true, or only one of them is true (which again the
ability to negate that result.) I.e. the Negate flag is applied to the combine result of any selected states.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 47
Browser Tab
There are a number of ‘list browser’ oriented widgets. These display a list of values (media categories, media items, values from a string
list field, etc…) in either a horizontal or vertical orientation. All of these share a common Browser tab that allows you to control the layout
of these list browser widgets.
In the designer the area of the
browser and of the slots are outlined
so that you can see where they will
be, usually used to align them over
some type of slots in an underlying
image or to insure that they are
sufficiently sized for touch purposes.
You can use the spacing and size
sliders to position those slots where
you want them.
The Numbered List check box will
automatically number the values in
the list, followed by a period, and
then the value.
The Horizontal Orientation check
box lets you flip the list orientation
either vertical (default) or horizontal.
The Text Ofs slider allows you move
the text right or left within the slots.
This is separate from text
justification on the font tab. It basically offsets the whole display area. It’s commonly used in numbered lists to move the text right to
display the numbers at a desired offset.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 48
Variable Tab
In any of the widget variations that let you associate the widget with a variable, you must indicate which variable you want it to use. You
have to enter the name manually since the variable won’t exist at design time. It must be a global variable, and include the GVar: prefix
that all global variables have.
Since the variable doesn’t exist yet,
there is no way to insure that the you
later create at viewing time will be
appropriately typed and limited for
the type of widget you’ve created. If
it isn’t, then the widget will act just as
it does when an associated field is
not available.
Note that you can change the
variable associated with a variable
based widget, at viewing time, by
sending a LinkToVar command to
the widget. This would normally be
done in an OnPreload action
associated with the template (which
is run after the template is set up,
but before it is initialized) based on
the value of one or more global
variables which have been
previously set. This is commonly
done in order to adapt a single
template to multiple audio zones or
multiple instances of devices of the
same sort.
You can also use LinkToVar at other times if you want, though normally it’s done while loading a template since the template is often
being loaded in response to a button press to view this or that device.
LinkToVar is available on any widget that uses the Variable tab, so it is not discussed separately in each individual widget below that
supports it.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 49
Xlats Tab
Some of the widgets support a translation mechanism. This allows you to indicate that if the actual value of the field is X, then display Y,
so that you are not limited to just the values that the driver uses to describe a field’s value. For instance, you could use it to convert the
English values of a field to another language for display.
You can add or delete translation items. In the example
above, if the field has the value VCR, it will be replaced by
D-Theater Deck. You don’t have to provide translates for
all the values, just the ones you want to translate. So in
the example above, the names for the other sources are
acceptable and are being taken as is.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 50
Cut and Paste
You can cut/copy and paste widgets in order to minimize the effort required to create similar sets of them. Just pop up the menu on the
widget you want to copy or cut select the Cut or Copy item. If you copy, then the original item is left as is and a copy of it is put on the
clipboard. If you cut, then the original item is removed and put into the clip board. You can then place the mouse pointer where you want
the upper left corner of the new item to be placed (on the template background), pop up the menu again, and select Paste to paste a new
widget into the template which is identical to the one you cut or copied. You can repeat
the paste as many times as required to create the number of copies desired.
Once you have pasted a new copy, you can adjust the attributes as needed to customize
each of the copies. You can also cut a widget from one template, then open another
template and paste it into the other template. This might be convenient to replicate one
widget from one template to another. But, if you are trying to create a new template much
like an existing one, just use the Save As item to save the original template under a new
name and modify it as desired.
You can also copy and paste just attributes. In this case, use the Copy Attributes and
Past Attributes menu items. Copy Attributes will pick up the attributes of the widget and
put them on the clipboard. You can then use the Paste Attributes item to paste those
attributes onto another widget. Those attributes that the two widgets have in common will
be applied to the target widget, and others will be ignored because they have no
meaning to the target widget type. You will be allowed to pick which categories of
attributes you want to paste:
Select the types of attributes you want to paste into the new widget and press Paste. The
new widget will update with the attributes it accepted.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 51
Widget Documentation
In this section, we will start covering the specific widget types. Each of these widgets will use one or more of the common attribute tabs
already discussed, but those details will not be repeated. Only the specific ways in which a widget is affected by those previously
discussed attributes will be mentioned. Except for the Template widget type being first, they are in alphabetical order.
The events generated by and commands accepted by each widget type are documented. But the standard commands that all widgets
respond to were covered at the start of this document, and will not be repeated here for each widget type.
Template
The template has four type specific attribute tabs. The Template tab allows you to set the CQC user account role required to access this
template. You set the minimum user type required to access the template. If anyone tries to access it, either by opening it directly or via
any navigation link from another interface, and they don’t have sufficient rights, they will be told that they cannot view it. By default it is set
to the Limited User, allowing any user
type to access it.
If you are create a template for an
open kiosk style display, you will want
to set it to Limited User because you
are going to want to auto-log the
interface viewer into the least privileged
The Use Focus check box enables or
suppress the focus mechanism. See
the section on Navigation/Focus near
the top of this document for an
explanation of focus and why you might
or might not want it. If you enable the
focus, you can control the color of the
default focus border and press color
border.
You can also add a text note to the
template, to remind yourself later about
details that might easily slip your mind.
The Edit Notes button will bring up a
text editor window to edit such notes.
The Action tab, in the case of
templates, allows you to define actions that are run when the template is loaded, and on a timed basis. The loading events are OnLoad
and OnPreload. OnPreload is fairly restricted, since the widgets are not fully set up at that point. Mostly commands that just set some
value on a widget that will be used later when it is initialized are allowed in the OnPreload. Do what you can there, since it is generally
more efficient, but other things will need to be done in the OnLoad. At that point, the widgets are loaded and initialized, but not displayed
yet, so more functionality is available.
Timeouts
There is also an OnTimeout event. It can be used to auto-exit the popup or to periodically update some visual display or something of
that nature. You invoke a SetTimeout() command on the template to set a timeout, either periodic or after a given time of inactivity by
the user. When that time expires, the OnTimeout will be invoked. It will continue to be invoked on that time period until it is stopped or
the popup exits. Only the top-most popup gets these events. Keep these actions very fast and failsafe, since the user is locked out while
an action is running.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 52
Hot Keys
There is a Hot Keys tab that allows you to configure actions that will be invoked in response to hot key events from RIVA clients. These
clients typically have hard buttons that you want to allow the user to press and invoke CQC actions. So you can configure an action for
any hot keys you want a given base template or popup (or overlay within one of those) to react to. When a hot key event is received by
the RIVA server, it will find the top level template (base or popup), and then start searching down the z-order for any overlays. Each
overlay is checked to see if it has mapped that hot key. If so, the action is run and that’s that. Otherwise the search continues. If no
overlay handles it, then the template or popup is searched. If it maps the key then that action is run. If not, and the template or popup
has an ‘Otherwise’ action configured, then that will be run. The Otherwise action is not run if it is configured in an overlay. This allows
unhandled keys to propagate to the template or popup and some default action taken.
Events
As discussed earlier in this document, you can configure templates to respond to event triggers, see the discussion of events in
interfaces above for details. It’s unfortunate that there is an overloading of the meaning of ‘event’, in that widgets that you interact with
send out events (such as OnPress, OnClick), since that makes for some confusion sometimes. But you can also set up the interface to
respond to incoming event triggers just as the event server does. The configuration is the same as in the event server.
Template Actions
You can also define template level actions. You give them a name which you can then use later to invoke them. These actions are
intended to reduce redundancy by storing common sequences of logic at the template level. There are restrictions on where you can
invoke these template level actions, since they are not allowed to be called on the loading of the template in and in some other
circumstances. Since these actions are generic, they sometimes depend on values being set into global variables before they are
invoked. They use those global variables to affect some specific field or variable and so forth.
Events Supported:





OnExit. This is a very restricted event which only has access to the global variables target. It is used to clean up global variables
upon exit of a popup. Without this, you would have to put such cleanup in any action that might cause the popup to exit, and you
still couldn’t handle the user pressing Escape on the keyboard. This gives you a way to make sure that global variable cleanup is
done no matter how the popup exits. For templates loaded as base templates or overlays, this is never invoked.
OnExtClick. If the user clicks outside of the current top level displayed template (i.e. top-most popup if any popups are visible),
this event is generated. This can be used for things like dismissing popups or pop-outs by clicking outside of it.
OnPreload. Generated after the template is created in memory, but before they are fully initialized. This is a fairly limited
environment and many commands are not available. But do what initialization type activity you can here, since it is generally the
most efficient. It knows it doesn’t have to redraw ever, so it just stores away info to be used in the initial display of the new
template.
OnLoad. Generated after the template is initialized but before it is displayed. Use this for anything you want to do at startup
which cannot be done OnPreload. Some things have to be done here because the widgets are not fully initialized until this point
and so can’tbe expected to react correctly to some commands.
OnTimeout. See above, this is generated if you set a timeout on the template and it is invoked as a popup. See the SetTimeout
command below.
Commands Accepted:
Note that some of the commands that affect templates are discussed above (in the ‘Actions in Templates’ section) because they are not
really targeting the template itself but they do affect it in some way.


DoLink. Though this is really a command that targets the Intf.Viewer target, it affects whatever contains the invoking widget at
viewing time. So, if a widget currently loaded into the base template invokes this command, it will be sent to the template to make
it reload.
SetImage. This command will change the background image of the template widget. It can be used to change the background
based on user preference perhaps. The ‘Use Image’ attribute must be set on the template or this won’t have any real effect. The
ImagePath is a path into the CQC image repository of the image to set.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 53

SetTimeout. Sets a number of minutes that define the timeout period for the template. An OnTimeout event will occur after either
this many minutes of inactivity or every interval of this many minutes, according to the parameters you pass. If the template is
loaded into an overlay, this command will be ignored since it has no meaning in that case.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 54
Animated Image
The animated image widget will cycle through a small set of images, providing a simple emulation of an animation. It’s not going to
provide the type of animation that a video based interface will. It’s just a simple rotation through a set of images. The widget is associated
with a field, and has the usual Values tab to let you indicate when the field has a True or False state. When the field value is evaluated as
False, then the animation stops, and it will just show the first image. When the value is evaluated as True, then the animation starts.
You can choose to have the first image not be part of the animation sequence. This can be quite useful. You can have the first image be
the ‘inactive’ image, and then when animation starts it can cycle through the rest of the images, which you may not want to include that
inactive image indicator.
Or, you can include the first image if you just wanted something like a fan that is either rotating or not rotating. In that case, the first image
is just one of the rotated fan blade images like the rest.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 55
Area Color Fill
The area color fill widget is very simple. It only uses the Basic tab, to allow you to pick the colors you want to use. The two background
colors are used in the normal way, to do a gradient fill, or set them to the same color to do a non-gradient fill. You can set the
transparent background attribute and the border attribute and use this widget to provide a border around a set of other widgets (but
make sure the area fill is behind the other widgets or it will prevent them from seeing any user input.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 56
Boolean Image
The Boolean image widget is a quite powerful one for displaying status information. It allows you to configure two images, one for a false
state and one for a true state, and displays one or the other of the images, according to its current state. It comes in the common Field,
Variable, and Static forms, so the current state can be driven by a field, a global variable, or just an internal state of its own that can be set
by sending it commands.
It uses a number of the attribute tabs already covered, including the Field/Variable, Values, Images, and Basic tabs. So it is associated
with a field or variable, and you set the desired expressions on the Values tab to evaluate the field/variable value to True or False. This
widget will then display either its true or false image, according to the evaluation of the expressions. The Static variant still has a Values
tab, but it’s usefulness is limited and generally you would just leave it as is.
Commands Accepted:

LinkToField/LinkToVar. You can tell it to link itself to a different field or variable from what it was initially configured to use.

SetOpacity. Allows you to modify the opacity of the image dynamically at viewing time. The opacity is a value from 0 to 255
(0xFF), where 0 is fully transparent and 0xFF is fully opaque. You indicate the name of the image to affect (which is its text on
the Images tab.) This one is available for all variants.
SetState. For the Static variant, this lets you set the internal state of the image.

Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 57
Boolean Text
Boolean text widgets are very similar to the Boolean Image widgets discussed above. These are available in Field and Variable-based
variants, and they will display one of two text
values, depending on how they evaluate the value
of the field or variable. No Static variation is
available for this widget.
In this widget, instead of selecting True/False
images, you enter True/False text that will be
displayed. And of course the Font tab is available
since text display is involved, so that you can set
the desired font attributes.
Since this one requires that you provide two
separate strings, it has its own Strings tab, instead
of the Text tab. These only allow for single lines of
text, not formatted text like the Text tab does.
You can enter text for both available states, or you
may just use one state. For instance, if you have a
widget that indicates something is wrong, you
might not want it to display anything until the error
state occurs, so you would only enter the text for
the state that corresponds to the error status.
You can also cause the display colors to change depending on the state, by checking the “Use state based text colors” check box. If you
set this option, then the normal colors are used for False state and the Checked colors are used if the widget is in True state.
Commands Accepted:

LinkToField/LinkToVar. You can tell it to link itself to a different field or variable from what it was initially configured to use.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 58
Calendar
The Calendar widget displays a standard sort of rows/columns type of calendar. It only displays the numbers for the days, and everything
else you can control to look however you want. Here is an example. Only the grid here is being displayed by the calendar. The days of the
week display is a standard text widget. The current money and year display also is a static text widget, which the calendar is keeping up
to date by sending it commands. The currently date is being highlighted here by both using a lighter color and using an image. The two
buttons are sending the calendar commands to move to the previous/next month.
Events Supported:

OnScroll. When the calendar is scrolled, this is set out so that you can keep any current month/year display info up to date
(such as the one between the scroll buttons in the example above.)

OnSelect. Generated when the user clicks on a valid date in the calendar. The selected date info is passed along in runtime
values so that you can respond to them.
Commands Accepted:

AdjustMonth. You can tell the calendar to move to the previous or next month by sending this command. This allows you to
scroll to past or future dates.

SetSelectType. When you click on a date, the calendar can send out an action event which you can react to. However, to
make it easier for you, you can set the selection type so that the calendar will only send the event if the selected date is today
or earlier, today or later, or any day. So if you only want the user to be able to select dates from now forward, you can set the
select type to today or later and don’t have to worry about filtering out earlier dates yourself, for instance.

GetMonth. You provide two variables which it will fill in with the current month and year.
Runtime Values Provided:

IntfRTV:SelDay, IntfRTV:SelMonth, IntfRTV:SelMonthName, IntfRTV:SelYear. When the OnSelect event is generated,
these values will be provided so that you can react to the particular date selected. When the OnScroll event is generated the
day value will not have meaningful data, only the month and year values.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 59

StdRTV:SelTime. This will be a timestamp for midnight on the day selected. It’s only really meaningful in the OnSelect event,
and otherwise will be empty. It will be in the form of a hexadecimal number, e.g. 0x37349841000. It is a standard CQC 100ns
time stamp since midnight, Jan 1, 1970.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 60
Check Box
The check box is a powerful widget that supports a number of appearances and can be used in a couple different useful ways. In a
sentence, it provides a way to display the true/false state
of the configured expressions (on the Values tab), and to
change that state when clicked on.
This can be as simple as, for instance, a check box that is
associated with the Mute of your A/V receiver that
displays the current mute state, and toggles the mute on
and off when clicked. Or it can be used in more complex
way, in which it invokes complex true/false actions when
clicked.
A check box contains the following elements:




An associated field and a standard set of true/false value expressions. The current value of the field, as evaluated via the
expressions, determines the True/False state of the check box.
True/False text values. One or the other of these is displayed depending on the True/False state of the check box.
True/False images (optional.) The true image is displayed when the state is True, and the false image is displayed when the
state is False. There are also true/false images for when the button has the focus, if you wish to use them, as well as an optional
overlay image.
It generates an ‘On True Click’ event if clicked when true and an ‘On False Click’ if clicked when false, so that the associated
action can be composed of commands that are carried out when true and others when false, i.e. it can do different things when
you click it, based on the current state.
The check box allows you to format the check box display either with the image to the left and text to the right, the text and image both
centered on each other, or the image to the right and text to the left,. Here are examples of each.
The first and last are more appropriate for readable fields, in that they indicate the current state, but they can be used for writeable fields
also. The centered scheme is commonly used for writeable fields, because it pretty clearly indicates that it is a button to press. But you
can use either style in either case, according to your needs.
Note that you can change the meaning of the check box by flipping the true/false images and text. Normally, the check box shows the
current state, i.e. if the state is true it shows the true stuff, else the false stuff. In some cases, you want it to show what is going to happen
when you click it, so in that case, reverse your images/text. That way, when the state is false, it will show the true stuff, i.e. what’s going to
be the case if you click it and flip the status, and vice versa.
You can also create a 'radio button' effect with Check Box widgets. If you have a set of check boxes, each connected to the same field,
and with each value expression set to make it true for a given possible value of that field, and with each true action set up to write its true
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 61
value to the field, then clicking on one of them will cause that one to become true and all the others to become false. In this case, you
don't need a false action, since you aren't trying to toggle the value, but only to set a given value when that particular check box is clicked.
You set another value to the field by clicking on another of the check boxes in the set.
The “Use state-based text colors” check box allows you to have the check box change colors based on whether it’s in true or false state.
In false state it uses the regular foreground colors for the text. In true state, it will use the extra colors. If this isn’t checked, it always uses
the standard foreground colors.
Events Supported:


OnTrueClick. Generated when the check box is clicked and the current state is true.
OnFalseClick. Generated when the check box is clicked and the current state is true
Commands Accepted:






GetState. Retrieve the current true/false state of the check box (either the variable, the field, or the static value, according
variation of check box it is.)
GetText. Retrieve the text for the current true/false state. That could be an empty string if there is no text defined for the current
state.
LinkToField/LinkToVar. For variable and field based check boxes you can change the field or variable from that which it was
originally configured to use.
SetOpacity. Allows you to modify the opacity of the image dynamically at viewing time. The opacity is a value from 0 to 255
(0xFF), where 0 is fully transparent and 0xFF is fully opaque. You indicate the name of the image to affect (which is its text on
the Images tab.)
SetNamedImage. You can update one of the named images (using the name as it appears in the Images tab) by sending this
command and the path within our image repository of the new image to apply.
SetText. Allows you to change the True or False text dynamically at viewing time.
Runtime Values Provided:

IntfRTV:StateText. The text of the state is going to become active, i.e. the opposite one from what was set when the button was
clicked. This assumes that you end up doing what is required to make that happen. But basically it is to tell you what the new
state would be.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 62
Color Palette
The color palette widget was primarily created in order to support the new color enabled lighting systems, like the Hue system, but it is a
general purpose widget that could be used to select colors for any purpose you might have. It will display a standard sort of color palette,
in the common HSV type of format, with hues arranged horizontally and levels of saturation going vertically. You can just touch and drag
your finger around. It will send out events that indicate what color
is currently under the touch point. It also remembers the last color
selected.
The data is sent out in a number of formats that might be useful.
These are listed below. Note that touching the palette only sets
hue and saturation. A separate means is required to set the
brightness level of the color selected. This can easily be done via
a slider.
Combining the Hue and Saturation values with a currently set
Brightness or Value level creates an HSV or HSB style color. The
color is also easily accessible as RGB as well, if that is more
useful.
The widget provides a GetColor() command that lets you indicate
what format you want to get the currently selected color in. You
can get the RGB format or the HSV format with integer or floating
point values. Note that the V part of the HSV format is just a default internal value of 0.8. As mentioned, you must provide that part via
some other means, since the palette only provides hue and saturation.

Note that you can’t use the standard widget color query methods because those are for things like background color of the
widget and whatnot. The color maintained by the palette is not a display color but a data value for you to use.
Events Supported:




OnPress. Generated when you initially touch the palette.
OnRelease. Generated when you release you finger from the palette.
OnDrag. Generated as you move your pressed finger around on the palette.
OnSet. Generated when you just click on the palette.
Commands Supported:

GetColor. Allows you to query the last color selected. It can be gotten in RGB, HSV integer and HSV floating point formats. Note
that the V part is just a default value since the palette only defines hue and saturation.
Runtime Values Provided:




IntfRTV:ColorRGB. The current color in RGB format.
IntfRTV:HSVInt. The current color in HSV integer format
IntfRTV:HSInt. The current H an S components of the current color. This is convenient if you are going to be combining it with
your own V component set via other means.
IntfRTV:HSVFloat. The current color in HSV floating point format
The HSV representation of the colors is as described below. They are comma separated values.



Hue. 0 to 360, either integral or floating point depending on which format.
Saturation. 0 to 255 for integral format and 0.0 to 1.0 for floating point format.
Value. 0 to 255 for integral format and 0.0 to 1.0 for floating point format.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 63
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 64
Command Button
The command button is the primary means of allowing users to make things happen from a template. The button invokes a user action,
which you configure. It uses the standard action configuration dialog to allow you set up the action you want to take. This one does not
introduce any new attribute tabs. If you want to use images for the button, the Images tab will allow you to select images for the unpressed, pressed, and focus states of the button, plus an overlay image. All of the images are optional.
The ‘overlay’ image is a useful one in many cases. In many cases a button doesn’t show any text, but instead it shows some graphic
indicator, such as a left or right arrow, next/previous chapter indicates, and so forth. If you use separate pressed, un-pressed, and focus
images, then you would have to have separate versions of them that had each of the various indicators you wanted to use pre-drawn into
them. That wouldn’t be practical, so the overlay image can be used to provide the indicator, and it always gets displayed over the other
images. This allows you to just use ‘button blanks’ for the various states, and generically use them in all the buttons, without having to
make a right button in all three versions, a next chapter in all three versions, and so forth.
There are three versions of the command button, one that has static text (set at design time, though it can be changed via commands
during viewing), a field based version what gets its text from a field, and a variable based version that gets its text from a variable. If both
text and images are set, the text will be displayed over the images. When using a static button, you can just not enter any text and only
display images.
Events Supported:



OnPress. Generated when the button is pressed down.
OnRelease. Generated when the button is released, whether inside the button or not
OnClick. Generated when the button is pressed and released inside the button. This is where the bulk of the work should be
done. See the comments on actions at the top of this document for details.
Commands Supported:


GetText. Allows you to query the current text of the button.
SetOpacity. Allows you to modify the opacity of the image dynamically at viewing time. The opacity is a value from 0 to 255
(0xFF), where 0 is fully transparent and 0xFF is fully opaque. You indicate the name of the image to affect (which is its text on
the Images tab.)
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 65
Cover Art Browser
The cover art browser allows you to browse the cover art from any CQC media repository driver. Media repositories are drivers that
contain information about media titles (music CDs, DVD movies, etc…) that are stored somewhere such as on a hard drive, such as a
J.River , DVD Profiler, or Charmed Quark media repository, or in a third party external media server. You associate a cover art browser
with a media repository driver and it
then provides all the browsing smarts.
You tell the cover art browser to
display information for a particular
media type (music/movies) and
category within that media type. It will
then display a scrollable list of cover
art for the selected media. Each item
represents a ‘title set’ which is either a
single or multi-disc DVD or CD title.
For instance, the Star Wars Trilogy
would be a title set, and it would
contain multiple ‘collections’, each of
which is one of the movies in that set.
If you click on a title set that contains
more than one collection, the browser
will display the contents of that title
set.
When you click on a title set that
contains a single collection, or on one
of the collections of a multi-collection
set, then you will generally either invoke a player to play that collection or some sort of preview screen.
The cover art browser has its own Browser tab where you can adjust the layout of the browser, and associate it with the desired media
repository driver. The layout is controlled by way of a separate template. This template represents the information to display for each title
or collection. The CAB will display as many rows/columns as it can, given the size of the layout template and the horizontal/vertical
spacing settings you choose. So typically you will size the layout template such that it provides an optimal fit for the number of rows and
columns you want to have.
The layout template can include static text and images, to provide decorative or value prefix type displays. And it can also include Media
Repo Text widgets, each of which can be set to display a desired piece of metadata for each title/collection displayed. So this allows you
to have the CAB show you basically whatever metadata you want during the browsing process, though of course some of it going to be
too big to include in the layout template, unless perhaps you are doing a large type, single title at a time sort of layout.
Additionally, you can also include a few special image widgets which are identified by their names. These will be updated dynamically to
achieve particular effects.



FocusImage. This is only used if you have enabled the focus mechanism. It should be a Boolean Image widget. The False
image will be displayed for the slots that don’t have the focus, and the True image will be displayed for the slot that has the
focus. If you just want to have the True slot do anything, don’t set a False image.
PressedImage. Similar to above, this should be Boolean Image widget. Normally it will display the False image, but when a slot I
clicked, the True image will be briefly displayed to provide the click feedback.
CoverArt. This should be a Media Repo Image widget, set to display either Large or Small art. It will be updated to display the
cover art for each slot. You will generally want to use the small art, see discussion above.
Since these are identified by their widget names, you can only have one of each, because you can’t have duplicate widget names in a
template.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 66
A default layout template will be initially set, just so that there is something there. But it may or may not be very useful for your particular
look and feel. Generally you will want to create your own.
As of 4.5, the CAB provides the Images tab and you can set images to be used for playlists (if the repository doesn’t provide playlist art)
and for those titles/collections that currently have no artwork. Before, these were hard coded to specific paths in the image repository, but
now they are set per-CAB.

You generally DO NOT want to set up the CoverArt image in the layout template to use large art. This will generally make things
slower and use up a lot of memory because it means that effectively every title or collection that you browse (and a lot that you
don’t since it has to pre-load ahead of you in order to provide smooth scrolling), is going to get cached and will have to be scaled
on each drag operation to fit the display area. Due to image caching it will also eat up a lot more memory. Some media sources
also make their large art overly large which makes it worse. At 100K, every ten images accessed is a MB of memory of memory,
and there can be thousands in a media repository. So consider this carefully. Only use the large art for the preview when the
user selects a title or collection.
The cover art browser is a powerful widget so it provides a good number of events, commands, and runtime values.
Events Supported:




OnScroll. Generated whenever a new page of content is loaded, whether by scrolling, loading a new category, opening a title
set up, or going back up out of collection view. It is generally used to maintain an “X of Y” type of display.
OnSelect. Generated when the user clicks on a title set with multiple collections, i.e. when it has opened up into collection view.
It is often used to set a static text widget to indicate the title of the set being viewed.
OnSelectCollection. Generated when the user clicks on a collection or on a title set that has only a single collection, and is
generally used to either kick off the playback or to invoke some sort of preview.
OnSet. Generated when the overall list being browsed changes. Generally used to update some static text widget to indicate the
current category. So, when you select a new category, or open up a new title set, or a new on the fly type of query. It also applies
when you use the Back or Up commands and move backwards across such boundaries.
Commands Accepted:












Back. Move back to the previous displayed page of items.
GetIsTitleLevel. A conditional only command that returns True if the CAB is currently displaying title set level info, else False.
GetMediaType. Let’s you query the media type currently being displayed in the CAB. This is available as a runtime value for
actions invoked by the CAB, but you may sometimes wish to get this info from the actions of other source objects.
GetSortOrder. Lets you query the current sort order of the CAB. The values you get back are the same as those you pass in for
the SetSortOrder() command below.
ScrollList. Tells the browser object to scroll left or right through list of cover art items. It will do an inertial scroll unless that is
disabled in the Base tab.
ScrollToChar. Sends the browser a character and tells it to jump to the first title (or artist if browsing by artist) that starts with
that character. Generally there are a set of command buttons set up to allow jumping to a particular character.
SearchByAudioFmt, SearchByArtist, SearchByActor,SearchByTitle. Allows you to search for specific groups of titles by
various criteria. See more on this below. Note that these are conditional commands. If no titles match the query, it will return
False, else True. So if you get a False result back, you can just pop up a ‘sorry, no matches’ message. If no matches resulted,
then the CAB will not update to show an empty list, it’ll just stay where it is.
SetCategory. Tells the browser object to start browsing a new category. Generally sent from a Category Browser object.
SetLayout. This command allows you to dynamically change the layout used. For instance, you might want to use a different
layout for movies vs. music. It will be used the next time the CAB loads something. So set it first, then load the new stuff to make
it take effect, by setting a new media type in the example just given.
SetMediaType. Tells the browser object what media type you want to browse. If you select a media type not supported by the
repository that the browser is associated with, an error will occur.
SetRepository. You can use the same browser object and switch between repositories, instead of having to create multiple
screens that effectively have the same information on them.
SetSortOrder. Tells the browser object to sort its contents by one of the available sort critiera.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 67

UpLevel. If the browser is in collection mode (i.e. displaying the contents of a title set), this will effectively back through
previously displayed pages until it gets back to the title set level and display that page. Otherwise you would have to do ‘Back’
through possibly multiple pages of collections in order to get back up to the title set level.
If you want to save the media type, category, and/or sort order last set, and re-apply them when the user comes back to the media
browser screen, you can store them in variables and put them back. Be sure to do this in the OnPreload, so that they will be set before
the CAB loads its initial contents, i.e. the values will just be stored away and used in the initial load, so you avoid the overhead and
unsightliness of a double load of the CAB.
Runtime Values Provided:




















MediaRTV:Artist. The ColArtist and TitleArtist RTVs contain the artist for the collection and artist, respectively. This one
contains the artist of whatever was just clicked on, so that you don’t have to figure that out yourself. It’s only valid when
something was selected (i.e. in the select or select collection events.)
MediaRTV:CategoryCookie. The repository driver’s identifier for the category currently being browsed.
MediaRTV:CategoryName. The human readable name of the category currently being browsed. Note that when you have a title
set opened up and are viewing the collections in the set, then this holds the name of the title (which is really now the ‘category’
being viewed.) And, if you have done a search and are looking at the results of that search, it will hold the search criteria that
was used, since that is now your ‘pseudo category.’
MediaRTV:ColArtist. The artist associated with the selected collection. Only valid on a selection collection operation.
MediaRTV:ColCookie. The cookie for the selected collection. If you clicked on a title set, it will be the cookie for the first
collection in the set.
MediaRTV:ColCount. The count of collections in the selected title set (or the currently opened title set.)
StdRTV:FirstIndex. The one based number of the first item displayed, within the list that is being displayed. So it’s either the
index of upper left title set with the current category, or the index of the upper left collection within the current list of collections.
Generally used with the title count value below to do ‘x of y’ type displays.
MediaRTV:ItemArtistList. The list of artist names for the items in the selected collection.
MediaRTV:ItemNameList. The list of names for the items in the selected collection.
MediaRTV:ItemCookieList. The list of cookies for the items in the selected collection.
MediaRTV:LocInfo. The location information for the selected collection. According to the location type, it will either be a
changer.slot indicator, a path to a single file, or a list of paths to files.
MediaRTV:LocType. Indicates the location type for the selected collection. It will be FileCol, FileItem, or Changer.
MediaRTV:MediaFmt. The value of the media type metadata associated with the selected collection.
MediaRTV:MediaType. Indicate the type of the media selected, which is usually used to invoke this or that player appropriate for
the type of media.
MediaRTV:TitleArtist. The artist for the title set that was clicked on. If a collection was clicked on, then this is the parent title set.
MediaRTV:TitleCookie. The cookie for the title set that was clicked on. If a collection was clicked on, then this is the parent title
set.
MediaRTV:TitleCount. The count of titles (or collections if you are viewing the contents of a title set) in the current list. Generally
used to do “X of Y” type displays. It’s a little bit inconsistent that there’s not a separate ‘Count’ that shows the count for the
current mode (as is the case for things like name and cookie), but this is for historical reasons.
MediaRTV:TitleName. The name of the title set that was clicked on. If a collection was clicked on, then this is the parent title set.
MediaRTV:TitleNumber. The number of the title (or collection) that was clicked on. Generally used to do “X of Y” type displays.
MediaRTV:TopLevel. If the CAB is currently at the top level (showing title sets, as opposed to showing the collections of a title
set), then this is True, else False.
The important things to keep in mind with the runtime values is that Scroll and Set events are not specific to any title set or collection, so
they will not provide any values related to a selected collection or title set. The only provide overall information like the first index, the
category cookie/name, total title/collection count, and media type. The select and select collection events provide that stuff, plus the
information about the thing clicked on. If the thing clicked on is a collection, then both title set information (for the parent title set) and the
collection clicked on are available.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 68
Some special cases are:




TitleCount, for historical purposes, holds either the current count of titles (if at the top level) or the total count of collections (if
browsing the contents of an opened title set.)
When doing searches (see below), the category cookie and name are meaningless, since there really isn’t any. When you open
a title set, the category text is set to the name of the title. When you do a search, the category name reported will be the pattern
that was searched for.
TitleNumber is is really an index, i.e. it’s a zero based index of the title set that was clicked on. It’s only meaningful in the
OnSelect event. FirstIndex, inconsistently, is really a one-based number. Unfortunately these backwards names cannot be
changed now without breaking things.
The primary purpose of the generic MediaRTV:Artist value is so that you can easily provide a ‘find all by this artist’ type of button,
without having to know if you are in title set or collection mode (and therefore figure out if you need to use the ColArtist or
TitleArtist values.) It will contain the artist for whichever mode you are in. This is not to say though that you cannot, for instance,
go to the artist of the containing title set when a collection is clicked on, hence both values are also made available, in addition to
this mode specific one.
Searches
In addition to browsing by category, you can also search by various criteria, using the SearchByXXX commands listed above. You can
search by titles, artists/directors, actors, and audio format. In the searches that accept strings (title name, artist and actor) you can use a
regular expression to match more than just a literal value. So it can either be a literal value like “The Beatles”, or a simple regular
expression, such as a “The .*”, which would search for anything starting with “The “. The period means any character and the asterisk
means zero or more of the previous thing. You have to indicate, for efficiency reasons, whether what you passed is a regular expression
or not, since it makes the searching a lot faster if the database knows it can do a simple text comparison rather than a regular
expression comparison.
For audio format searches, you can search for titles that are <, >, <=, or >= some specific bit rate, bit depth, and sample rate, in order to
find audio of specific formats. Any titles returned will match all of the critiera, i.e. it’s an AND type search. This search only works for
music, not movies.
You can change the sort order and media type in the process as well, since effectively you are creating a new pseudo category. If you
don’t want to change these, you can query the current values and pass those back in again for new searches. The searches are not
case sensitive.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 69
Digital Clock
The digital clock widget does not display any field data, so it is somewhere between a data display widget and a static ornamentation type
widget. It displays the current time on the local machine, so
you should sync system clocks if it is important that all
machines in your network display the same time.
This widget uses the Basic and Font attribute tabs, to allow
you to control the fonts and colors and background
attributes of the clock, and also provides a Clock tab, which
allows you to set clock specific attributes.
You can indicate whether you want to use 24 or 12 hour
display formats, and whether you want to show the panels
and/or borders around the individual numbers. The panels
make it look like some digital clocks where each digit is on
its own LED panel. The panel sizes are driven by the
characteristics of the selected font, so they can differ quite a
bit as you select various fonts.
The raw text format will force the panel settings off, and
causes the text to be displayed just as unornamented text,
with locale specific am/pm indicator and in the 12/24 hour
setting indicated.
If you don’t want any of the special digital clock style display features, just use the Time/Date Text widget, which has much more flexible
formatting options. The digital clock is somewhat evolutionary baggage at this point because of that.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 70
Digital VU Meter
The digital VU meter is associated with a numeric readable field or variable, which has a range type limit of reasonable
size, and displays the current value of that field relative to its range. It mimics the common VU meters of music equipment,
which display the current volume of their device as a function of its overall range, using a set of green, yellow, and red
LEDs. Here is an example of a VU meter to the right.
The Meter tab allows you to adjust the percentages of the range that is taken up by each of the low, mid, and high ranges,
and you can set in the Images tab what images you want to display for each of these ranges. So, in the above example, will be green
LEDs for the low range, yellow for the mid-range, and red for the high range.
In the Images tab you can provide
both unlit and lit versions of each of
these images, so as to mimic the
lighting up of the images as the
range changes. If you only want the
lit versions to show up, don’t set any
unlit versions.
You can set the orientation of the
meter to go in the direction you
would like, but of course the images
you provide must work in the
orientation you choose.
All of the images must be the size in
the direction of the meter, so the
same height for vertical or the same
width for horizontal. If not, then the
display will not be right.
There are pre-fab image sets for all
orientations for the look of the
example above, but you can create
your own easily enough.
You can also control the spacing between the images in the direction of the meter.
Commands Accepted:

LinkToField/LinkToVar. You can tell it to link itself to a different field or variable from what it was initially configured to use.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 71
Driver Image
There are a number of ways to display images in your user interfaces. Drivers, however, normally don’t do this, not directly anyway. There
is not an ‘image field’ that drivers can use to serve up image data. However, there is a standard backdoor command that this widget
defines. Any drive can implement this backdoor command and this driver will download that image data and display it. This allows for an
open ended means for drivers to
serve up arbitrary images as
required.
The backdoor command is via
the QueryBufVal command, in
CML drivers. It allows for both
small and large versions of the
image to be provided, via two
different query value ids,
“CQCQueryLrgDrvImg” or
“CQCQuerySmlDrvImg”. The
DataName value is arbitrary and
defined by the driver. This
allows it to serve up multiple
image types under different
names. The driver
documentation should tell you
what names are available and
what image sizes.
time the field changes, it will go back and query the image data again and display the new image.
The driver must also provide a
field which it changes any time
the image changes. This widget
will watch that field and, any
This widget has its own tab, which currently just asks you for the data name to request from the driver. It doesn’t currently support
indicating which size to query. You must also select the appropriate field to monitor in the Field tab.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 72
Enumerated Image
Enumerated images are quite powerful widgets which can make your interfaces both informative but also attractive. It can be associated
with a readable string field or variable, which has an enumerated limits type, which means that the field/variable has a small, fixed number
of known textual values. This widget allows you to associate an image with each of the possible enumerated values and, when the field or
variable has that value, the widget will display the associated image. So, instead of just displaying the text of the currently selected
source, you might display an image of a DVD, or VCR, or satellite dish, according to whether the DVD, VCR, or satellite input is the
currently selected source.
This widget does not introduce any new configuration tabs.
Commands Accepted:

LinkToField/LinkToVar. You can tell it to link itself to a different field or variable from what it was initially configured to use.

SetOpacity. Allows you to modify the opacity of the image dynamically at viewing time. The opacity is a value from 0 to 255
(0xFF), where 0 is fully transparent and 0xFF is fully opaque. You indicate the name of the image to affect (which is its text on
the Images tab.)
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 73
Graphs
The Logic Server, besides its usual job of allowing you to combine multiple field values into a single field value in some way, also supports
graphs. You can define ‘graph fields’ just as you define other Logic Server fields, though they are not real fields, and they are not exposed
via the Logic Server Driver. Instead, they are exposed via the Graph widget in the interface system. A graph widget can be associated
with one of the graph fields (directly from the
Logic Server, not through the driver), and it will
at viewing time just periodically ask for the graph
data and display it in a standard right to left
scrolling fashion.
When you configure a graph widget, you will
select the graph to display, a vertical scale type,
and minimum/maximum values for the graph.
The scales supported currently are Linear and
Logarithmic, which are the most commonly used
styles in graph display.
The minimum and maximum values indicate to
the graph widget what it should consider the
values at the top and bottom of the graph to be,
and hence where to position each graph point
vertically based on its value. Any values outside
of this range are displayed as a line along the
top or bottom of the graph widget.
So you could set the minimum/maximum values
larger than the actual range of the field being
graphed and that would make the actual graph line show up more towards the middle of the graph area. Or you could set it smaller than
the actual range of the field because you know that in your situation the value will never actually stray outside of the limits you have
entered, and thus get more vertical resolution out of the graph display (i.e. not waste any unused vertical area.)
Graph objects in the Logic Server are updated, at most, once a minute, so the graph object will only update once a minute at most as well.
Note that the viewer caches graph data, so if you have accessed a graph once, it will continue to maintain the graph data active for a
number of minutes in case you come back again fairly soon to a template that displays that graph data. This allows the data to be
displayed more quickly. If a graph hasn’t been accessed for a while, it will be dropped and the next template that accesses that graph will
cause the graph data to be downloaded again before display.
Graphs only contain 60 data points, so it doesn’t make a lot of sense to make the graph objects a lot larger than that horizontally, though
in some cases you may do so for greater legibility. The graph object will interpolate values for those pixels that fall between actual graph
points.
The graph widget, at this time, doesn’t display any sort of legends or grid lines. That is left up to you to provide. You can find various grid
line images for linear or logarithmic graphs out there. If you want to display the times represented, you can use a Time Text widget. These
support an offset in hours, so you can put one on the right side for the current time, and one on the left side that has been offset by the
number hours represented by the graph.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 74
List Browser
This widget has no type specific attribute tabs. It is a browser, so it uses the standard browser tab to set the horz/vertical layout of the
browser, size of the items and so forth. There are field and static versions. The field version can only be associated with fields that are of
string list type. The static version you have to load a list into yourself, in the form of a list of comma separated quoted values, or you can
load it from the enumerated limits of a field or variable. Each item in the list can have a separate user data value associated with it, which
is not displayed. It can be used to trigger some event to occur when an list item is clicked on, in those cases where the displayed item text
(or the index of the selected item) itself is not sufficient for that purpose.
For focus purposes you can define a focus and pressed image that will go behind the item in the list that has the focus or is being
pressed.
Events Supported:

OnSelect. Generated when user clicks on an item in the list.
Commands Accepted:
The setting methods below are only valid for static lists, since the contents of field based lists are controlled by the field itself.













GetCount. Puts the count of items currently in the list into a provided variable. It also returns a False result if the list is empty, or
True if the list is non-empty, which can be useful to avoid an extra check of the returned count for zero.
GetIndex. Puts the index of the item at the top of the list (zero based) into a provided variable. If the list is empty, the result will
be False, else it will be True, so you can use this in a conditional command to check for an empty list and not do something
crazy. If the list is empty, the value of the index returned will be a maximum 32 bit value.
GetText. You can get the text of a given item by its zero based index. The text will be put into a provided variable. It returns True
if it was able to return the requested text value, else False.
LinkToField. For field based browsers, you can tell it to link to a different field from what it was initially configured to use.
ScrollList. Tells the browser object to scroll the list in various ways, i.e. next/previous page, up or down by one, to the first or last
page, etc…
ScrollToIndex. Tell the browser to put the passed index at the top of the browser. It may not be able to do so exactly, since it
always displays a full page of items if it can. But it’ll get as close as possible.
SetBrowserList. For static browsers, this lets you set up the list with text values to display. In this case it’s a single list, so just
display text, no background information is stored. The list is a quoted comma list. It can also be empty, to clear the list.
SetBrowserList2. Similar to the previous command, but this one takes two lists, one is the visible display text and the other is
the list of background values, one for each visible value. Both are quoted comma lists. They must of course be the same size or
the command fill fail. * See comment below
SetDblBrowserList. This is a special version of the previous command, where both lists are in one parameter, separated by a
new line. The reason for this version is because you may query a driver for list info, and the text query backdoor commands can
only return a single text string. So the driver can put them both together with a new line between them. Both lists of course must
be the same size. * See comment below
SetFromEnumFld/SetFromEnumVar. These can be passed the name of a variable or field which is of an enumerated sort. It
will query the possible enumerated values of the field or variable and load the list with those values. In this case it’s only possible
to set the visible text. The background values will be empty.
SetText. You can update the display text for the list entry at a given index.
SetUserData. You can update the background user data value for the list entry at a given index.
When using the SetDblBrowerListX commands, be sure that the value is not mangled by command parameter expansion. If you
get the value from a driver, by reading it into a variable. When you pass the content of that variable to these commands do it like
this: %(LVar:MyLists, “^1”). The formatting control part of the token is set to ^1, which means don’t modify or expand the contents
at all. If you don’t do this, the new line that separates the values can get mangled and the command will fail.
Runtime Values Provided:

StdRTV:SelectIndex. The zero based index of the selected item.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 75


IntfRTV:ListItemText. The text of the selected item.
IntfRTV:UserData. The text of the background user data for the selected data. If none it will be empty.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 76
Line
This widget type draws horizontal or vertical lines. It’s very simple, you just indicate the orientation and whether you want line end caps or
not. There are currently only a small number of line cap types, but more will likely be added in the future. You can also indicate whether it
is a thick or thin line, with thin
being a single pixel and thick
fattening it up a bit.
Anything thicker than that is
better done with the Area Fill
widget.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 77
Live Tile
This widget type supports the modern ‘tile’ paradigm. It’s fairly common in modern interfaces to have a ‘home’ page that consists of a set
of ‘live tiles’, which display basic information and which, when clicked, will take you to a page that provides more detailed access to that
information.
Live Tiles in CQC are essentially a
combination of a non-interactive
overlay and a button. So you tell it to
load the contents of another template,
and will load those widgets contained
in the loaded template and make those
its own content. It will discard any
interactive widgets since the contents
of tiles are purely for display purposes.
As with overlays the contents can be
changed dynamically at runtime by
loading a new template.
When the tile is clicked it will invoke an
OnClick event that you can respond to
by invoking some action. Usually a tile
is associated with some functional
area, music, weather, etc… and shows
basic information about that function.
When clicked, it will load a new overlay
that provides more fine grained
access.
A tile doesn’t just have to just load a single, fixed template, though it can be set up that way. Instead, you configure a list of templates it
can load. And you select one or two fields that will be used as the criteria for deciding what to load. For each configured template, you can
set expressions on the fields that will evaluate their values at viewing time. CQC watches the configured field(s) for changes. When one
changes, it will go down the list and evaluate each expression. The first template whose expressions come out true will be loaded. You
don’t have to use both expressions for every template, even if you define both fields. You can set it to <Unused> to ignore it. You have to
define one of them though, for every configured template.
Additionally, for each configured template, you can define a global variable and a value to write to it. So, you might actually always load
the same template, but for different conditions you might load it with a different global variable value, on the assumption that the
OnPreload/Onload actions of the template will make use of that variable to set itself up, such as linking to different fields. So, you might
have the tile automatically switch to the source media renderer that you have selected for the current room or something of that nature.
So, in the example configuration tab above, the top half is the overall configuration. When you select a new template on the right side, the
bottom half shows you the configuration for that template. You can move the templates up and down in the list, which is important since
the first one that matches is loaded, so order can count.
Efficiency
One big concern with live tiles is that, since they are like overlays and load a template to display their contents, they will not be instantly
populated when a template is loaded that contains tiles. They can only be loaded one at time, and the IV engine has to get down the
values of the fields that control which template is to be initially loaded before it can load it.
So, you generally don’t want to have a home screen with, say, sixteen tiles, that you replace with an overlay on every selection and then
reload when you come back to the home screen. Instead, do something like create a main overlay and load a 2x wide template into it.
The left side contains the tiles, and the right side contains an overlay. When a tile is selected, load the right side with the desired overlay
and ask the parent overlay to scroll left to show the newly loaded overlay. A home page button on the right side can make it scroll back
to the left, to display the tiles, which are still there and already showing current information.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 78
Logo Image
This is a specialized image display widget that is mostly used for mapping channel numbers to logo images, hence the name, but it could
be used for other types of mapping. In most cases where a channel is involved (cable, sat, sat radio, etc…) the driver will provide a
channel number field to indicate the currently active channel. If you have images that are named after the channel numbers, it is fairly
simple to them display an image that is associated with the
channel.
You associate this widget with some device field that provides
the mapping numbers, and a scope in the CQC image
repository where the corresponding logo images are stored. The
widget just watches the field for changes and displays the image
for the current value if there is one available.
In addition to the already introduced Field, Image, States, and
Basic tabs, this widget has a Logo tab, where you can select
from the pre-fab or custom image repository paths and adjust
the opacity of the image. During design, the designer will display
an image for the value zero, so be sure to add an image named
“0” even if one is not usually required.
CQC currently ships with two sets of logo images, one for
DirecTV and one XM Radio. Others may be added later and you
could in the meantime load your own images into the repository
and use them in a similar way. There are radio buttons for the
image sets provided with CQC and a Custom option that allows you to enter some scope of your own.
A common use for the logo image widget is to use an alternative set of weather condition images with the Weather Channel driver. There
is a specialized Weather Channel image widget (see below) that uses the images provided by the Weather Channel kit, but some folks
prefer to use others, and there are some nice looking sets out there for this purpose. You just associate the widget with the appropriate
weather condition field, choose the Custom image setting, and point it at the image repository scope where you have uploaded the
alternative images.
Commands Accepted:

LinkToField. You can tell it to link itself to a different field from what it was initially configured to use.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 79
Mapped Image
Mapped images are similar to enumerated images, but where enumerated images only work on enumerated device fields or variables,
mapped images work for any type of field or variable. Generally, enumerated images are much more commonly used, since any field or
variable that has a small number of
meaningful values will be an enumerated field,
because that is just a more convenient way to
present the values to the user. But, if you
have a field that has a small set of, say,
numeric values, you could use the mapped
image to achieve a similar effect to the
enumerated image for those numeric values.
The Mappings tab allows you to add, delete,
and edit mappings. These are just names to
give some human readable meaning to the
map able values. When you add a new
mapping name, you will be asked first for the
name to give it, and then you will be asked to
provide an expression that can be used to
evaluate the value of the field at runtime. The
first mapping in the list whose expression
returns true is the one whose image will be
used. You can move mappings up and down
in the list to control this evaluation order.
This expression is operating on the value of
the associated field or variable. Select an expression type and if it requires a comparison value, provide that value. You can also negate
the result which will evaluate the expression and then flip the Boolean result and use that flipped value as the value of the expression.
Once you have added the desired mapping items,
go to the Images tab, and you will see that each of
your mappings is now in the images list and you
can assign an image to them
Commands Accepted:

LinkToField/LinkToVar. You can tell it to link itself to a different field or variable from what it was initially configured to use.
.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 80
Marquees
The marquee widgets display the current value of an associated field or variable, or a static fixed text value, and scroll it right to left over
and over, in the classic marquee style. If the text will fit within the widget area without scrolling, then it doesn’t actually do the scroll. It only
does it if needed.
Effectively marquees are just text widgets (see below) which scroll the text. They are the same otherwise, and use the same attribute tabs
as the text widgets and support the same commands, except that you generally wouldn’t want to use a marquee with the commands that
are intended to implement things like entry fields for keypads and such probably.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 81
Media Category Browser
Media repository drivers provide lists of media titles (CDs, DVDs, etc…) that are based on categories (genres basically.) You basically
want to be able to select a category to browse, and then instruct a cover art browser to start browsing that new category. This requires a
widget to allow you to browse the categories and
then, when clicked on, to generate a command to
the cover art browser. This widget provides that
functionality.
This widget has one type specific tab. The Repo tab
that allows you to select the repository you want this
browser to be associated with and to select the
initial media type it should display when loaded (if
the repository supports more than one.) Any
currently loaded repository drivers will show in the
drop down list, so just select the desired one.
In many cases, you want to get as many categories
across as you can, so make sure that the ‘No Text
Wrap’ setting in the Basic tab isn’t turned on. This
will allow multi-word category names to wrap. Just
make sure you have enough vertical space in the
slots to hold more than one line. If you don’t want
them to wrap, then enable the no text wrap setting.
It provides a standard Browser tab to allow you to
control the layout of the list .
Events Supported:

OnSelect. Generated when user clicks on a category. Generally used to send a Set Category command to a cover art browser
to make it start browsing that category.
Commands Accepted:



ScrollList. Tells the browser object to scroll left or right through list of categories.
SetMediaType. Tells the browser to switch to a different media type and display the categories for that type. If the type is not
supported by the associated repository, this command will fail.
SetRepository. You can change the repository that the category browser is browsing. This is mostly intended to allow you to
avoid having multiple media browsing interfaces that basically all have the same contents, but just reference a different
repository. When you select a new repository, it will reload with the new categories. You should generally also send the same
command to the associated cover art browser.
Runtime Values Provided:



MediaRTV:CategoryCookie. The repository driver’s identifier for the category clicked on.
MediaRTV:CategoryName. The human readable name of the category clicked on.
StdRTV:SelectIndex. The zero based index of the selected item.
A media category browser is usually configured so that when it is clicked on (and sends the OnSelect event) that the associated action will
invoke the Set Category command on a cover art browser. The Category Cookie parameter of that command is provided by the Category
Cookie runtime value that the category browser provides.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 82
Media Image/Media Repo Image
When creating media browsing interfaces, you tend to always want to do two things. One is to allow the user to preview a selected
CD/DVD title by viewing its metadata before committing
to playing it. The other is to have a ‘now playing’ screen
that shows metadata on what is currently playing. For
image based metadata, the Media Repo Image and
Media Image widgets, respectively, handle those
operations.
The Media Image widget supports showing the cover art
for the media currently playing in a media renderer
device driver. This widget introduces no new attribute
tabs. It asks the renderer for the cover art image data
and just displays whatever the renderer returns.
You associate the Media Image with the playlist item
key of a renderer. This key is a unique representation of
the current item (in whatever form is valid for the
renderer), and this widget will go ask for new cover art
whenever it changes, on the assumption that the image
may have changed.
The Media Repo Image is associated with a media repository driver and can show either the cover art or the MPAA rating logo for a title.
The repo versions are passive widgets and they will only show something if you send them a title or collection cookie, i.e. they are for
content preview.
So generally you will have a cover art browser send them a cookie when the user selects a collection. This widget has its own attribute tab
to allow you to select the repository driver it should be associated with, and which metadata image it should display. Any currently loaded
media repositories will be available to select from.
You can choose large or small art in the Attribute combo box. Sometimes you don’t need or want the large art because it would just have
to be scaled down for display anyway or you are viewing on a wireless device and want to reduce overhead.
Commands Accepted (Media Image):

LinkToField. This can be used to link it to a different field from what it was originally configured for. It has to be the playlist item
key field of a media renderer driver.
Commands Accepted (Media Repo Image):



SetRepository. You can ask a repo widget to associate itself with another repository than what it was originally configured for.
SetTitleCookie. Tells a repo widget to update itself for a new title cookie.
SetColCookie. Tells a repo widget to update itself for a new collection cookie.
If you send a title cookie, it will act as though you sent it the collection cookie for the first collection in the title set, so generally you
will want to send it a specific collection cookie.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 83
Media Item Browser/Media Repo Item Browser
These two widget types are very similar; they only differ in where they get their information from. When you want to preview a music
collection, generally you want to present a list of the items in that collection as well, at least for visual consumption but often also to allow
just individual songs to be queued up or allow the user to select items in the playlist and so forth. The Media Repo Item Browser does
that. You associate it with a media repository, then at viewing time you send it a collection cookie and it will display the items in that
collection.
The Media Item Browser does something similar but
shows the current playlist queued up in a specific
media renderer driver. So it is associated both with a
media repository, and with the ‘play list serial number’
of a media renderer driver. Any time that playlist serial
number changes (which will happen any time the
playlist is modified in the renderer driver), this widget
will go back and get the new playlist and update to
display those changes.
So they effectively both display lists of media items,
just from different sources.
In most cases with an item browser, you will want to
make sure that the ‘No Text Wrap’ setting in the Basic
tab is turned on. This will prevent the track names
from wrapping to multiple lines if longer than the width
of the slots. They will just clip instead. But if you
make the slots big enough to handle more than one
line, you can certainly allow them to wrap if you want.
When you select an item in the list the index, unique id, item cookie, associated text, etc.. are made available as runtime values so that
you can use them in item selection driven actions. The unique id can be used to select or delete the item by writing to renderer fields.
Events Supported:

OnSelect. Generated when user clicks on a track slot.
Commands Accepted:





GetText. Retrieves the displayed text of one of the items in the list, by its zero based index into the list.
SetColCookie. For repo item browsers, this is used to set the collection cookie, which tells it what collection you want it to
browse the items of. The cookie must be associated with the repository that the widget is currently associated with.
SetRepository. For repo item browsers, this can be used to associate it with a different repository than what it was originally
configured for.
ScrollList. Tells the browser object to scroll up or down through list of cover art items.
LinkToField. For item browsers, this can be used to associate it with a different field from what it was originally configured for.
Runtime Values Provided:






MediaRTV:ItemArtist. The name of the artist associated with the selected item, if available.
MediaRTV:ItemCookie. The repository driver’s identifier for the selected item.
MediaRTV:ItemName. The name (the displayed text) of the selected item.
MediaRTV:ListItemId. In an item browser, this is the unique id of the selected item. This can be used to ask the target renderer
to select or delete the item.
MediaRTV:LocInfo. The location information for this item, from the repository (a file/directory path or changer/slot indicator
generally.)
MediaRTV:MediaRepoMoniker. The repo moniker that the selected item is from, and hence that the item cookie is relative to.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 84

StdRTV:SelectIndex. The zero based index of the selected item.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 85
Media Item Browser (Advanced)
The Media Item Browser above is fairly low calorie and will serve the needs of many solutions. But, if you want something more complex,
then there is an advanced version of the media item browser. In this one, instead of just displaying the titles of the items in the playlist,
you define what information is displayed and it’s visual layout by way of a separate (smaller) template that defines the per-list slot layout.
So you create a small ‘layout template’ that the browser will use to draw the contents of each list slot. The height of the layout template
defines the height of the list slots, and any of the layout contents that exceeds the width of the browser will be clipped off. So you need to
make the size of the layout template generally the width of the browser itself (or size the browser to fit the width of the layout), and not
make the height any higher than it really needs to be so that you can get as many slots visible as possible at once.
The layout template can only contain a small subset of widgets. Any unsupported widgets will be ignored. The currently supported set is:




Static Text. These provide their usual function, that of labeling things. You typically will label the information you are displaying
so that it’s clear what is being presented.
Static Images. Generally used for decorative purposes.
Static Boolean Images. This is a special one. They are used to provide context sensitive display, discussed below.
Media Repo Text. These provide the meat of the content. Generally these are used to display specific metadata values
associated with media repository collections or items. In this case, they are used to tell the browser to display specific metadata
values associated with the media item driving each browser slot.
Static Boolean Image widgets display one of two images, depending on an internal true/false state. In this advanced media browser
widget, they are used for the special purpose of indicating things like which item in the list represents the currently playing item, and to
provide pressed emphasis when the user presses a slot. So you can add them to the layout template, and give them particular widget
names to indicate their purpose. Currently the supported ones are:


CurItem. The true image will be shown for the slot that is showing the currently playing item, else the false image. You can of
course only set a true image, so that nothing is displayed for the non-current item slots.
PressedImage. The true image will be shown for the slot that is currently being pressed down by the user, else the false image.
Here again you can set just a true image so it only does anything for the pressed slot.
Any Boolean images widgets that don’t have these names will be ignored. You could have more than one of each if it makes sense,
perhaps to light up on the left and right sides or something like that.
Events Supported:

OnSelect. Generated when user clicks on a track slot.
Commands Accepted:


SetMoniker. Change the repository moniker that all of the widgets in the layout template reference, so that you can switch it to
look at a different renderer driver on the fly.
ScrollList. Tells the browser object to scroll up or down through list of cover art items.
Runtime Values Provided:







MediaRTV:ItemArtist. The name of the artist associated with the selected item, if available.
MediaRTV:ItemCookie. The repository driver’s identifier for the selected item.
MediaRTV:ItemName. The name (the displayed text) of the selected item.
MediaRTV:ListItemId. This is the unique id of the selected item. It can be used to ask the target renderer to select or delete the
item.
MediaRTV:LocInfo. The location information for this item, from the repository (a file path or changer/slot indicator generally.)
MediaRTV:MediaRepoMoniker. The driver moniker of the repository this browser is associated with, i.e. from which this other
runtime value info was extracted (not provided in the repo version.)
StdRTV:SelectIndex. The zero based index of the selected item.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 86
Media List Browser
The media list browser is sort of like the Cover Art Browser above, and would be used in similar situations, in that it is associated with a
media repository driver and allows you to browse through the media in that repository. But in this case, instead of being cover art based, it
is just a simple text list based browser, much like those used in iPods and other such portable media devices. It starts with a list of
categories. When you select one, the list is replaced with the title sets in that category. When you select one of those it is replaced with
any collections (or directly to items if only one collection exists in that title set.)
This makes it considerably lighter weight than the cover art browser, and potentially better suited to smaller hand held wireless devices,
since it doesn’t require pulling over lots of cover art and the display of the data is much lighter weight as well.
It provides many of the same sorts of runtime values and events as the Cover Art Browser since it needs to accomplish similar sorts of
things. It accepts navigation commands to move back upwards in the list after you have drilled down, and for scrolling up and down
through the lists that are larger than a single displayed page’s worth. This widget doesn’t introduce any new attribute dialog tabs, and is
pretty straightforward to set up.
Events Supported:




OnSroll. Sent when he CAB is scrolled. This is typically used to update a current page number or current X of Y type display.
OnSelect. Generated whenever the user selects an actual media item. In this case, the list browser doesn’t do anything itself, it
just tells you about the selection so that you can start that item playing or whatever you want to do with it.
OnSelectCollection. Generated when the user clicks on a collection or on a title set that has only a single collection, and is
generally used to either kick off the playback or to invoke some sort of preview.
OnSet. Generated when the list being browsed changes, not in terms of scrolling but a new list being loaded. Generally used to
update some static text widget to indicate the current category or title set or collection is being displayed. See the
MediaRTV:Name runtime value below, which is what you would generally use.
Runtime Values:















MediaRTV:Artist. The ColArtist and TitleArtist RTVs contain the artist for the collection and artist, respectively. This one
contains the artist of whatever was just clicked on, so that you don’t have to figure that out yourself. It’s only valid when
something was selected (i.e. in the select or select collection events.)
MediaRTV:CategoryCookie. The repository driver’s identifier for the category currently being browsed.
MediaRTV:CategoryName. The human readable name of the category currently being browsed. Note that when you have a title
set opened up and are viewing the collections in the set, then this holds the name of the title (which is really now the ‘category’
being viewed.)
MediaRTV:ColCookie. The cookie for the selected collection. If you clicked on a title set, it will be the cookie for the first
collection in the set.
MediaRTV:ColCount. The count of collections in the selected title set (or the currently opened title set.)
MediaRTV:ItemArtist. The artist associated with the selected item, only used for the OnSelItem event.
MediaRTV:ItemCookie. The item cookie of the selected item, only used for the OnSelItem event.
MediaRTV:ItemName. The name of the selected item, only used for the OnSelItem event.
MediaRTV:LocInfo. The location information for the selected collection or item. According to the location type, it will either be a
changer.slot indicator, a path to a single file, or a list of paths to files.
MediaRTV:LocType. Indicates the location type for the selected collection. It will be FileCol, FileItem, or Changer.
MediaRTV:MediaFmt. The value of the media type metadata associated with the selected collection.
MediaRTV:MediaType. Indicate the type of the media selected, which is usually used to invoke this or that player appropriate for
the type of media.
MediaRTV:Name. This a generic name value that holds the name of whatever the thing selected was, either via user selection
or by navigating backwards in the list to a previous list. This is generally used for showing a ‘what are you seeing now’ indicator
since you don’t have to figure out what bit of information to display based on what event you are receiving.
MediaRTV:TitleArtist. The artist for the title set that was clicked on. If a collection was clicked on, then this is the parent title set.
MediaRTV:TitleCookie. The cookie for the title set that was clicked on. If a collection was clicked on, then this is the parent title
set.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 87

MediaRTV:TitleName. The name of the title set that was clicked on. If a collection was clicked on, then this is the parent title set.
Commands Accepted:




Back. Tells the list browser to move back to the previous list that was displayed, if any is available.
Reset. Deletes any cached info so that the browser will re-download information again as it is accessed.
ScrollList. Tells the list browser to scroll the currently displayed list up or down.
SetRepository. Allows you to have the list browser change the repository it is associated with.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 88
Media Repo Text
As with the Media Repo Image widget above, when creating media browsing interfaces you will often want to provide a preview mode,
where the user sees the metadata for the selected title
before committing to playing that title. This widget will
display one of a set of available textual metadata fields
for a given title or collection. This widget is completely
passive and it will only display something after you send
it a SetTitleCookie or SetColCookie command to tell it
which title or collection to display information for. So
normally you will have the cover art browser send it a
cookie to it when the user selects a title.
If you send it a title set cookie, it will use title level
information where that exists. Otherwise it will have to
use data from the first collection within the title set. In
the case of the Title attribute, it will actually display the
title set title, followed by a dash, and then the collection
level title text. This is generally very desirable, so that
you get something like “Fellowship of the Rings – Disc
2”, or “Star Wars Trilogy – Episode IV: A New Hope”,
where the first part is the title given to the title set and
the second part is the collection level (disc level) title.
This widget has its own attribute tab so that you can select the metadata field you want to use, and the media repository that it should be
associated with. You can also send it commands to dynamically change at viewing time what metadata field it displays.
Commands Accepted:




SetColCookie. Tells the widget to update itself for the passed collection cookie.
SetTitleCookie. Tells the widget to update itself for the passed title cookie.
SetRepository. This can be used to map the widget to a different repository than what it was originally configured for.
SetTextType. You can use this command to make the widget change at viewing time which media field it should display.
If you send a title cookie, it will act as though you sent it the collection cookie for the first collection in the title set, so generally you will
want to send it a specific collection cookie.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 89
Numeric Text
The numeric text widget is similar to dynamic text widget, in that it just formats the value of an associated field, and displays that formatted
value. However, whereas the dynamic text widget just displays a default formatted value, this one is specialized for numeric fields
(cardinal, floating point, integral) and provides a lot more
control of how those numbers are displayed. In the Field tab
you will only be presented with fields of a numeric type,
since that is all this widget understands.
This widget supports the already discussed Field, Font, and
Basic tabs. It just adds a new Format tab that allows you to
control the formatting of the numeric value.
The main control is provided by the three radio buttons in
the upper left. They control the overall formatting of the
value.
Locale format does locale specific formatting, and is what
you get for numeric fields in the Dynamic text widget. It
uses whatever are the locale specific settings for formatting
numbers. Raw format just formats the basic digits without
any extra stuff, and only uses negative signs and decimal
points where appropriate, but nothing else. The Custom
format allows you to control all the settings.
On the right side of the tab, you can set some 'decoration'
values. The only two available at this time are the leading and trailing text. These allow you to enter fixed text values that are always
displayed before and after the formatted numeric value field. Note that they don't count as part of the field width. The value is formatted
into its field width and the leading and trailing text are displayed before and after the full field width.
Below the radio buttons are a set of formatting controls. They are described in the list below.





Use Groups. Indicates whether 'thousands groupings' should be done. This is only available in the Custom format. So when set
you get "1,234" and when not set you get "1234", though the size of the group and the separate character will be whatever is
appropriate for the locale no matter what format type is selected.
Field Width. This controls the width of the 'field' into which the formatting value is placed. So you can make the field wider than
the actual value, and place the value within that field. How it fits within this field is controlled by the justification and fill character
values. To make the field just fit the formatted value, set this to zero.
Fill Char. If the field width is wider than the formatted value, you can fill the rest of the field with this character. It can be spaces
or zeros or underlines. Where those fill characters are displayed is controlled by the justification.
Justify. If the field width is wider than the formatted value, you can adjust how the field fits within the field, to either left justified,
centered, or right justified.
Dec Digits. If the value is floating point, this controls how many decimal digits are displayed to the right of the decimal.
Commands Accepted:

LinkToField. This can be used to link the widget to a different field from what it was initially configured for.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 90
Overlay
Overlay objects exist purely to contain templates that are loaded into them at viewing time. It is designed to allow for flexible reuse of an
area of a template, to load up various smaller templates into that area as needed, usually through buttons or a toolbar that send
commands to the overlay object. When
a template is loaded into an overlay all
of the child widgets of that template are
adopted into the container and become
its new contents.
The position of the overlay object
controls the position of the templates
that will be loaded into them, and any
loaded widgets will be clipped to its
display area. You would generally
design the templates to be loaded into
an overlay so that they are the exact
same size as the overlay object they are
being loaded into, so that they fit exactly
into it and are not clipped. But, if the
contents are larger than the overlay, you
can use gestures to scroll the contents.
A single finger gesture can be used as
long as you do not do it over a widget
that reacts to that type of gesture. On
multi-touch hardware you can use a two
finger gesture on overlays.
You must set the widget id on all
overlays, in the Basic tab, because an overlay is useless if it cannot be a command target, since that’s how it gets told to load up new
templates into itself at viewing time.
You can indicate an initial overlay to load when the containing template is loaded, or you can leave it blank until some overlay link button
is used to load an overlay into it.
You can also disable velocity-based scrolling when using gestures, and do purely page at a time scrolling (where a page is the width or
height of the display area.) Note that this is separate from the ‘no inertial scroll’ option on the Base tab, which prevents the sliding scroll
effect. This affects the amount of movement, whether sliding or not. Use the “Paged scrolling mode” check box to disable velocity
sensitivity.


Note that overlay contents are currently only scrollable if they have a background fill. They cannot be transparent since that
would require that every widget type be able to draw an alpha-transparent version of itself, which isn’t currently doable. If the
background fill is solid, then the overlay can be scrolled in either direction. If it is one of the two color fills, then the overlay will
only scroll in the direction that the background fill remains consistent. I.e. if it has a vertical fill, it will allow you to scroll
horizontally because the background doesn’t change in the horizontal direction when you use a vertical fill.
Note that, with one exception, the display attributes of the overlay itself are always used, not those of the loaded templates. The
one exception is that, if the overlay has a background image, that image is always used. If there is not a background image set
on the overlay, then any background image set on the loaded templates will be used.
Aspects of the loaded template that are adopted by the overlay are: any action commands, hot keys, or triggered events, and of course
the actual child widgets themselves.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 91
Events Supported:



OnLoad. Generated when a new template is loaded into the overlay. It is generated post-load, so by the time the event is
processed the overlay should have the new template contents loaded.
OnScroll. Generated when the overlay is scrolled around via gestures or command. RTVs with the current ‘page number’, i.e.
what multiple of the overlay size is visible on the top and left side, are passed.
Scroll. If you aren’t using gestures to do scrolling, then you can use buttons to send scroll commands to the overlay. If in paged
mode it goes a whole width/height (depending on the scroll direction indicated), else it will go about three quarters of the width or
height of the overlay area.
Commands Accepted:


LoadOverlay. Tells the overlay object to load a new template.
SetInitTemplate. You can change the initial template to be loaded, allowing you to dynamically decide (in the OnPreload of the
containing template) what the initial template will be.
Runtime Values:


IntfRTV:HPageInd. A horizontal ‘page index’, which can be used when the overlay is in page scrolling mode to update a display
indicating which page number is visible. It is a zero based value. It is based on which multiple of the overlay width is visible on
the left side.
IntfRTV:VPageInd. A vertical ‘page index’, which can be used when the overlay is in page scrolling mode to update a display
indicating which page number is visible. It is a zero based value. It is based on which multiple of the overlay height is visible on
the top side.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 92
Progress Bar
The progress bar is a specialized widget for showing the value of range based numeric fields or variables, by way of a color fill bar that
progresses from left to right, top to bottom, right to left, or bottom to top. The field or variable must have a range limit so that the progress
bar knows how much of the available range the current value represents. The current range part is filled with one color and the unused
part is filled with another color.
Though the representation is by a color bar, it’s not just a simple, flat color. Instead you must provide a mask image.
The mask image defines the opacity for the color bar. The actual color of the mask image
doesn’t matter, only the alpha channel is used (the per-pixel transparency info provided by 32
bit PNG images, so the source image must be such a 32 bit PNG.)
The progress bar will steal the alpha mask information from the mask image and apply it over
an in-memory bitmap that it then does the color fill into. This allows for some quite elaborate
visuals uses of this widget. Here is an example of a thermometer created using the progress
bar, on the left. A background image which just provides the outline of the thermometer, with
a little Gaussian blur around it is used to provide the background image. The background is
shown on the right. The background is not required, or it may just be part of an underlying
image.
Then a mask image is provided that limits the color fill to the area inside the background, and
which provides a nice glare effect by allowing the white of the background to show through.
The colors have been set to red to provide the ‘mercury’ of the thermometer, and black to fill
the rest of the fill area.
Creation of the fill image can be a little tricky if you want to create the glare type effect shown above. For just a rounded type effect, it’s
pretty easy. Something like this will
work. It’s just a rounded rectangle in which the
image has been made slightly
transparent around the edges. This will create an
effect of a slightly rounded fill bar
because the center of it will be the actual fill
colors while the edges will blend in
with whatever the underlying background is.
Remember that the red color
makes no difference. All that matters is the
transparency in this case, so the
red color was just used to make it easy to see
what the shape is.
If you want to create a glare type effect, you have to be more careful about the actual color of the fill image because you want to have
some of it to actually be maintained. So it gets a little trickier. Here is the fill image for the thermostat above, set against a purple
background so that you can see what it’s doing. The areas you see in white are fully opaque, so the fill color will be
fully red there. The parts you see in purple are where the fill image is partly to completely transparent, and allowing
the background to show through. Because the interior of the background image (above right) is white, that means
that it will allow that white to show through, creating the glare you see in the thermostat image (above left.)
So you have to kind of think backwards when creating this kind of fill mask. What you would generally do is create
thermo shape (so that it fits inside the background where appropriate.) Then you would create the glare parts and
layer them over it. Then use the glares to create an inverted transparency mask on the underlying basic shape. So
wherever the glare parts were transparent, that makes the underlying part opaque, and vice versa, creating the
desired mask. And of course it also still depends on using the correct color underneath it, since that color is going to
show through. If we’d made above right background image yellow inside, the glares would be yellowish.
Note that you can do quite elaborate things once you figure out this basic effect. You could do tank fill levels,
volume meters, a volcano with lava showing through the cracks, a segmented LED type of display, etc… It’s quite a
flexible tool.
When associated with a field, and that field is writeable, then you can drag the progress bar to change the value of the field.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 93
The progress bar attribute dialog allows you to control which direction the progress bar will go in. You can select up, down, left or right.
You can also choose whether to file the
unused portion of the bar or not. In the
thermostat example above the black part is
the part where the bar isn’t being drawn,
and normally it would be filled with the
appropriate color. But you might not want to
do this. You might want to just let the
background show through the unfilled parts.
You can also allow the progress bar to be
used as an input mechanism. For a static
variant, it will just update its internal value.
For field and variable variants, it will update
the field or variable. In the field case, the
field has to be writable of this setting will be
ignored. To set the value, you just click at a
given point, or click and drag to adjust the
value.
Commands Accepted:


LinkToField. For field based progress bars, this can be used to link the widget to a different field than what it was initially
configured for.
SetValue. Only available for the static version, this allows you to change the value programmatically.
Events Supported:




OnPress. Generated when you first touch the bar.
OnDrag. Generated as you move your finger after pressing down
OnRelease. Generated when you raise your finger at the end of the drag.
OnSet. Generated when a new value is set on the progress bar, either by just clicking or after you release and the new value is
stored.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 94
Slider
The Slider is a specialized widget for showing and/or setting the value of range based numeric fields or variables (and there is a static
version that just maintains an internal value), by moving a thumb slider up/down or right/left along a slider track. You select an image to
use for the thumb slider, but there is no background image for a slider. So you can layer it over any type of slider track image you want to
use. The slider will move along the track to represent the currently value within the defined range limits.
For field based sliders the Field tab will only show those fields that are at least readable numeric fields, and which have a range based
limit of a size that is reasonable for a slider. For variable based sliders, the variable you associate it with must be created at viewing time
with a numeric type and range limit. For the static version you will be allowed to indicate the range you want the internal value to be able
to move within. You can also control whether the slider will will automatically write the new value to the field, or not. You may want to just
react to the user releasing the slider yourself and do more than just write the value to the field.
You can click on the slider and move it along the track to set a new value (for field based ones only if the field is writeable.) The value will
not be set unless you release the thumb
slider with the mouse pointer within the
parallel sides of the widget along the
direction of travel. I.e. if it is a horizontal
slider, as long as you release above the
lower edge and below the upper edge of the
widget, the value will be set. If you move
below or above the widget area and release,
nothing will be done and the slider will go
back to its original position.
The direction of travel is indicated simply by
the shape of the widget. So make it long and
low and the direction of travel will be
right/left. Make it tall and skinny and the
direction of travel will be up/down. The
bottom/left represents the low end of the
value range, and top/right represents the
maximum value.
As of CQC version 4.1, you can also provide
per-user type range limits for this type of
widget, which allows you to limit the range of
settings available to different types of users. For instance, you might want to prevent any but system administrators from turning the
volume up past -5db, for instance. If you don't check the 'Enforce User Limits' field, then the full range of the field will be available to all
users. If you check it, then the user type combo box becomes enabled and you can select each user type, and use the sliders to the right
to adjust the available range for that user type.
Events Supported:




OnPress. Generated when you press down to start a volume adjustment.
OnRelease. Generated when you release, whether inside the button radius or not.
OnSet. Generated when a new volume is set, i.e. when you press and release at a legal spot and a new volume is written to the
field.
OnDrag. Generated as you drag the slider. DO NOT do anything here but update some other widget. Do not try to write to a field
here, because the values come out far too quickly. Normally this is used to keep some static text widget or progress bar updated
to show the drag value.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 95
Commands Accepted:



LinkToField/LinkToVar. For field or variable based progress bars, this can be used to link the widget to a different field or
variable than what it was initially configured for.
SetValue. Only available for the static version, this allows you to change the value programmatically.
SetRange. Only available for the static version. This command lets you change the min/max values (which define the range)
dynamically. It’s very useful for things like a generic popup that lets the user set a value. In such a situation the min/max values
may change each time the popup is invoked, so you want to be able to pass them into the popup and set up the slider to
accommodate those values.
Runtime Values:

StdRTV:CurValue. The current value of the slider. During dragging this is the value you’ve dragged to, not the value actually set.
The sider doesn’t have any textual display of the value, and it doesn’t set the new value as you drag the thumb slider. It will only set the
new value when you release, so it’s nice to know what that will be before you release and to know what the current value is. The slider,
like the volume knob, sends out OnDrag events, which you can use to, for instance, update a static text widget with the value that would
be set if the volume knob was released. You can keep such a textual representation of the value always updated by sending it the current
value in response to both OnSet and OnDrag events. Any time the slider value changes, that will cause an OnSet that will update the
display, and the OnDrag will keep it updated during drag operations.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 96
Special Actions Button
The special actions button is like a standard command button in visual and interaction terms, but instead of invoking one of your own
configured actions, it invokes one of a set of special, CQC
defined actions. In addition to previously discussed attribute
tabs, it introduces its own Action tab.
The only setting here is which special action you wish to
invoke. Just select the action from the Available Actions
combo box.
Note that these sometimes have different meanings based
on whether the special action button is in a base template
or in a popup/popout type template. And they don’t address
the current template contents at all, instead providing more
global type functions that affect the computer or the viewer
instance that the template is running in.
The available actions are:





Invoke the Blanker. Invoke the blanker window. The blanker covers the whole screen with a blank window, which is used to
darken the screen when desired. Just touch the screen to make it go away. See also Blank and Blanker below.
Exit the Interface. This action will exit the current interface. In the standalone viewer, this will close the viewer (after asking if
you want to.) In the Admin Interface, it just closes the current interface window.
Exit Full Screen. This action can be used to exit the full screen mode via a button. It also assumes that you want to allow any
user to exit full screen mode since it is an openly exposed mechanism. In a kiosk type system you would never use this, since
you want to insure that viewer stays completely full screen.
Display Off. Powers off the primary display, using the power management features of Windows.
Blank and Blanker. A combination of invoking the blanker and blanking the screen. This is often the best choice because it both
completely eliminates light leakage and the blanker window eats the first touch that wakes the screen back up, so that the user
doesn’t inadvertently invoke some operation in the process of waking up the screen.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 97
Static Image
Static images are used for decorative purposes. They just display some fixed image, such as a horizontal separator image or a decorative
cornice type image. In some cases you would just embed these images in the actual template background image, but that's not always
feasible or desirable.
This widget doesn't introduce any new attribute tabs. The Basic tab is provided to allow you to control background colors and border and
such. The Image tab allows you to select the desired image to load, and set the positioning and opacity, as was previously discussed.
Commands Accepted:


SetImage. Tells the static image object to load a new image. The parameter is the path in the CQC image repository of the new
image to display. As always with paths, be sure to use double slashes just in case.
SetOpacity. Allows you to modify the opacity of the image dynamically at viewing time. The opacity is a value from 0 to 255
(0xFF), where 0 is fully transparent and 0xFF is fully opaque.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 98
Text
Text widgets allow you to place decorative or descriptive fixed text on your templates or to display the value of fields or variables in text
form. This widget uses the already discussed Basic, Font, and Text attribute tabs, and their uses in this widget are pretty obvious. Static
text widgets take a text value at design time to display (though they have some other uses as well as discussed below.) Field and variable
based text widgets display the value of their associated field or variable, respectively.
The static text widget is kind of a special one because it provides various commands that allow you to modify the text value it is
displaying. These commands effectively allow you to implement simple, single line text editing, commonly used in login or password or
search popups. A set of buttons are provided to send a static text widget commands to enter letters and/or numbers, backspace, clear,
etc…
It also provides a command to send the value it currently contains to a field, and to deal gracefully with the fact that it might be rejected,
generating an OnError event that you can respond to by displaying an error message to the user and letting him try again. So it’s a pretty
powerful tool for user interface creation.
The Marquee widgets (documented above) are effectively extensions of these more fundamental text widgets, which just scroll the text
value instead of displaying it in fixed position. It wouldn’t make much sense to use a scrolling marquee as a text editor type widget, but the
same commands documented below for the static text widget are available on the static marquee.
There are some specialized text display widgets also, which deal with special types of values that you may want more control over the
format of, e.g. the time/date text widget or the numeric text widget. When you use a regular text widget for a field or variable, you’ll get the
default format for the type of the field or variable. You can set the radix and decimal digits on a numeric variable when you create it, to
provide some more control over the display format.
For the field and variable based text widgets, you can still enter some fixed text. You just put a %(f) replacement token in the text
somewhere and that will be replaced by the actual formatted field or variable value. This lets you do something like “Value =10” without
having to create a separate static text to provide the Value= part. The reason the token is ‘f’ is because historically there were only field
based widgets, not variable based, so ‘f’ mean the ‘field’ value. But it works the same for variable based ones.
Commands Accepted (Static version only)
Append. Sends the static text widget some text to append to its current text
Clear. Tells the static text widget to clear out its text and display an empty string
DeleteLast. Tells the static text widget to delete the last character in its current text, if any. Basically it is like a Backspace button
on the keyboard.
GetText. This command will put the current text of the widget into a provided variable.
SendValue. This one will make the static text widget send it’s current value, optionally formatted into a string by replacing the
%(v) token with the text value, and to write that to a string field of a device.
SetMaxChars. Sets the maximum number of characters that the field should accept via Append commands. When the maximum
character length is reached, subsequent Appends are ignored.
SetPattern. Allows you to set a regular expression pattern to drive acceptance of characters sent via the Append command. Any
new character is temporarily appended to the current contents, and verified against the regular expression. If it fails, then the
new character is ignored.
SetSecretMode. This command allows you to put the widget into secret mode, in which it will just display asterisks instead of the
actual characters of its text content. Usually used for implementing login screens.
SetText. Tells the static text widget to start displaying a new string of text.









Events Supported (Static version only):

OnError. This is only generated by the SendValue command. If the field write invoked by SendValue fails, then this event is
invoked. You can use it to react to the error and display some sort of message to the user, either via a popup or writing it to a
static text widget generally.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 99

OnSuccess. This is only generated by the SendValue command. If the field write invoked by SendValue works, then this event
is invoked. You can use it to inform the user of success, or to handle any followup activity that should be invoked after a
successful field write (though generally that would just be done in the subsequent action steps after the SendValue command.)
Runtime Values (Static version only):

StdRTV:ErrorMsg. Only available during the OnError event, this contains the error text, should you want to display it to the user.

When you configure the Send Value command, if you use the replacement token discussed above, then the %(f) must actually
be \%(f), because it will otherwise look like a runtime value and will cause an error because there is no such runtime value. Using
the slash in front of the percent sign escapes it so that it is not interpreted as the start of a runtime value.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 100
Time Image
This is a quite specialized image display widget that is primarily used to create analog clocks, but could have various other uses. It uses a
time (local time for a static variant, or time based field) to drive one or two images. It takes the current time and breaks it down to current
hour and current minute values. These two
values can be used to select respective
images.
You indicate an image repository scope for
one or both value. Within that scope must be
images for each minute and/or hour value.
So, for the hour scope there must be 0 to 23
images and for the minutes value it must be
0 to 59.
At viewing time, the widget watches for the
hour or minute value to change. It then uses
the scope and hour/minute value to build an
image path, and displays that value.
image file for hour value four would be:
The actual images don’t have to be named
literally 0, 1, 2, etc… For each scope you are
required to provide a file name pattern,
where %(n) is in the pattern somewhere.
That is replaced with the current hour or
minute value to create the actual image path.
For instance, in the example above, an
\User\TestAG\800x500\Clicks\Hands\SimpleWhite\Hour_4
Both images are centered within the width and overlaid over each other. For its standard intended use, the images would be images of
clock hands that with transparent backgrounds, so when overlaid they create the clock hands display.
You could though use any times of images you want, so if you can find some other use for this widget by doing so, then have at it.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 101
Time/Date Text
This widget allows you to display time or date information in a very flexible way. If you used a standard text widget, it would display a time
stamp as just the raw numerical value, which is generally not what you want. Normally you want to be able display particular aspects of
the date or time. So this widget introduces a tab that allows you to indicate the format of the timestamp display, and to assign an offset in
hours. This offset is applied to the time value before it is formatted for display.
There are field based and static versions of this widget. The field based one is associated with a field that of time type. The static version
just displays the local system time/date.
The “Time Fmt” tab looks like this:
To get the desired format, you use a set of replacement tokens. You can mix these tokens in with any other text required. The list of
available tokens is:

















':' – (colon) The localized time separator character
'/' – (forward slash)The localized date separator character
'a' - The localized abbreviated day of the week
'D' - The day of the month as a number
'd' - The localized name of the day of the week
‘e’ – The elapsed seconds
‘E’ – The elapsed minutes
'H' - The hour in 24 hour terms
'h' - The hour in 12 hour terms
‘l’ – (lower case L) The millseconds
'M' - The month as a number
'm' - The localized abbreviated month name
'n' - The localized full month name
'P' - The localized AM/PM designation
's' - The seconds
'T' - The localized time zone name
't' - The local time zone offset from UTC, in minutes
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 102



'u' - The minutes
'Y' - The year as a 4 digit value
'y' - The trailing two digits of the year
You use these in standard replacement tokens that are used in various places of CQC. They are in the format %(x,w,f), where x is a
character that identifies the token (and will be one of the letters in the list above), w is the width of the field to put the token value into, and
f is the fill character to use if the value doesn’t take up all of the width. If the width is a negative number, it means left justified in the width,
else it’s positive to indicate right justified. Only the identifier part is required, the width and fill are optional.
Here are some examples:
Source String
Replacement Text
Results
"%(A)"
"123"
"123"
"%(A,5)"
"123"
" 123"
"%(A,-5)
"123"
"123 "
"%(A,5,'$')"
"123"
"$$123"
Commands Accepted:
 LinkToField. For field based time text widgets, this can be used to link it to a different field from what it was initially configured for.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 103
Toolbar
The toolbar is a very useful widget in many interfaces. Basically it is the equivalent of a horizontally scrollable list of command buttons.
The purpose of this widget is to allow you to get a lot more buttons onto a limited screen area than you could if they were all visible at
once. Of course, post 4.5, you could now create a scrollable overlay with any contents you want, but the toolbar is still more convenient,
and more efficient, for what it does.
Each button has a text caption and an image, both
of which are optional, though you’d obviously use
at least one if not both. It also has an associated
action that is invoked when the button is clicked.
This widget is fairly complex, so it has two of its
own widget specific tabs. These allow you to do the
following things:





Define new buttons
Set the text and/or image for each
button and control their layout.
Configure the action to invoke when
each button is pressed.
Control the size and spacing of the
toolbar button slots so that you can
position them as desired over
background image slots
Control the vertical position of the
buttons’ contents within the toolbar area.
At design time, the layout of the toolbar is represented by an outline of the overall area and of each toolbar slot position. This allows you
to correctly place it over any desired underlying template image that might have slots for them to fit into. Pressing anywhere in the slot will
invoke that button, not just on the image or text, so
constrain the area of the slots appropriately for your
needs.
The toolbar supports the focus mechanism, by
providing a focus image in the Images tab. This
allows the focus emphasis to be moved through the
list of visible buttons until a desired match is found.
It also provides a pressed image if you wish to use
one, which will be drawn under the button
text/image when the button is pressed, usually to
provide some sort of ‘lighting up’ effect.
You can choose to have the text and image of the
buttons displayed in one of three ways; either text
below and image above, text above and image
below, or both centered. The latter is generally
used to make them look like actual buttons with text
on them, as opposed to desktop-like icons with text
underneath them. In any of these cases you can
adjust the vertical offset of the text/image
combination up or down within the vertical size of the toolbar, so as to place them as required. For instance, you might want to indicate
focus by way of a glowing underline image, in which case you would want to push them upwards a bit to allow for that underline image.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 104
The “File slots” option will cause, when the toolbar background is set to transparent, the background fill settings to be used on each slot
separately. This can be used to create a desirable effect sometimes, instead of using a background image if all you need is a simple flat
or gradient fill.
A common use for the toolbar is on a main template, where each button loads a template into the main overlay area. This allows you to
support lots of overlays without having lots of buttons visible. Put a command button on either end to handle scrolling it back and forth,
and possibly a home button to bring it back to the home position. Put the most commonly accessed buttons in first, and less commonly
accessed ones as you go right. So the home button always brings you back to the important stuff with a single click.
Images
In addition to the per-button images, the Images tab let you select some other images that are used for specific display conditions. They
are listed below in order of precedence, i.e. if a later condition is true that image will be displayed instead of the previous ones.




Background. You can have an image displayed behind all of the buttons if want, perhaps in lieu of just creating a single image
that you would put behind the toolbar as a whole. The advantage being that they scroll along with the buttons.
Marked. You can mark toolbar items at viewing time. Only one can be marked at a time. The marked one will display the Marked
image behind the button contents, and it will use the Marked colors for the text instead of the regular text colors. Marking is done
by index, and you can query the current marked index. A typical strategy is to have the action of each button mark itself, so that
the last selected one is marked.
Focus. If you use the focus mechanism, the slot with the focus will display this image behind the button contents.
Pressed. When you click a button, the clicked effect will temporarily display this image behind the button contents.
Events Supported:



OnPress. Generated when a button is pressed down.
OnRelease. Generated when the button is released, whether inside the button or not
OnClick. Generated when the button is pressed and released inside the button. This is where the bulk of the work should be
done. See the comments on actions at the top of this document for details.
Commands Accepted:






DelTBItem. Deletes the toolbar item at the indicated index. Be careful of this since it will many any indices you have embedded
in toolbar oriented commands could be affected. Use the FindByText command to look up items to avoid issues.
FindByText. Looks up a toolbar item with the indicated text and fills in a variable with the index of that item if found. Returns
True if it finds the item.
GetMarkedIndex. Puts the index of the marked button into the provided variable, if any. If none is selected it returns zero, just so
that it can return a valid index, but the True/False result will indicate whether something was marked or not, so you can tell the
difference. If you know something is always marked you can assume the value is valid. Else you can use this as a conditional
command and only do something if it returns True.
MarkByIndex. You provide the zero based index of a button and a True/False value to indicate if you want to mark it or unmark
it. If it’s not currently marked, then an unmark command is ignored. If it’s not currently marked, a mark command will remove the
mark from any previously marked button and set it on the indicated one.
ScrollList . Tells the toolbar to scroll left or right, go to home or end, etc… Normally you will just drag it via gestures, but you can
also drive it via other widgets if desired.
SetButtonText. Allows you to dynamically change the text of a button in the toolbar. You provide the 0 based index of the button
you want to change and the new text.
Runtime Values:




StdRTV:CurText. The text of the clicked on item that caused the action to be invoked.
StdRTV:FirstIndex. The zero based index of the button that is currently at the left-most visible position.
StdRTV:MarkedIndex. The index of the currently marked index, if any. If there is none, this will be an empty value.
StdRTV:SelectedIndex. The zero based index of the button that was invoked, i.e. the one that caused the action that receives
this runtime value. This can be used to mark the selected button if you want.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 105
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 106
Volume Knob
Volume knob widgets are input widgets which allow you to adjust the value of a range based numeric fields or variables. Generally
speaking, volume fields are most likely to fall into this category, hence the name. But, any field or variable which is of numeric type, and
which has a range based limit that has a reasonably
limited range that would make sense for this type of
widget can be used. There is also a static version that
just maintains an internal value, in which case you are
allowed to configure the min/max values it should
move within.
The volume knob uses the Image tab since the widget
itself draws only the little red LED that rotates around
the center of the widget to indicate the position of the
knob. You have to provide some meaningful
background against which that rotating LED is viewed.
You might not use the Image tab if the template
background contains the image of the knob, but in
most cases you will provide an image of a volume
knob as the background of this widget.
It also provides a Knob tab, which allows you to control
a number of attributes of the volume knob. The first set
contains the Radius and Range settings. The Radius
slider, the first one, allows you to control how far out
from the center of the widget the LED will be, so that
you can place it at the appropriate place within the background image. The range controls the range of travel around the center, from
bottom left (minimum value) to bottom right (maximum value), so that you can make the min/max points of travel line up with any min/max
tick marks that might be in the underlying knob image.
You can also provide per-user type range limits for this type of widget, which allows you to limit the range of settings available to different
types of users. For instance, you might want to prevent any but system administrators from turning the volume up past -5db, for instance.
If you don't check the 'Enforce User Limits' field, then the full range of the field will be available to all users. If you check it, then the user
type combo box becomes enabled and you can select each user type, and use the sliders to the right to adjust the available range for that
user type.
Here is an example of the volume knob to the right. In this case, a nice background image has been placed
behind it, and the radius adjusted so that the LED travels just inside the rotating part of the knob, and the travel
range has been adjusted so that the min/max ticks line up. When you are in the designer, the value will be set to
the maximum value of the field's range so that you can correctly align the LED with the maximum tick mark
during range adjustment.
To use the volume knob widget at runtime, you can either just click where you want the LED to go to, or you can
press and drag left/right (or up/down) to lower or raise the value. When you release, the new value you have selected will be written to
the field or variable, or the internal state if a static one.
Events Supported:




OnPress. Generated when you press down to start a volume adjustment.
OnRelease. Generated when you release, whether inside the button radius or not.
OnSet. Generated when a new volume is set, i.e. when you press and release at a legal spot and a new volume is written to the
field. You can do other things in addition to the automatic setting of the new value, if needed.
OnDrag. Generated as you press and drag on the knob. DO NOT do anything here except to update some other widget. Do not
try to write to a field. The values come out far too quickly for that.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 107
Commands Supported:


LinkToFld/LinkToVar. For field and variable based volume knobs, this allows you to link the widget to a different field than what
it was initially configured for.
SetValue. This is only for the static version, to allow you to change the value programmatically.
Runtime Values:

StdRTV:CurValue. The current value of the volume knob. During dragging this is the volume you’ve dragged to, not the volume
actually set.
The volume knob doesn’t have any textual display of the value, and it doesn’t set the new value as you drag it around. It will only set the
new volume when you release, so it’s nice to know what that will be before you release and to know what the current value is. The volume
knob, like the slider, sends out OnDrag events, which you can use to, for instance, update a static text widget with the value that would be
set if the volume knob was released. You can keep such a textual representation of the value always updated by sending it the current
value in response to both OnSet and OnDrag events. Any time the volume knob value changes, that will cause an OnSet that will update
the display, and the OnDrag will keep it updated during drag operations.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 108
Weather Channel Image
This is a specialized image display widget that should be associated with the one of the 'icon code' fields of the Weather Channel XML
Feed driver. It will display the appropriate image to represent the weather conditions represented by the icon code. This saves you a lot of
time building up a mapped image widget to do the same
thing, and it is more efficient since it does not try to locally
cache all the images as a mapped image would. It just
downloads the images as required.
The images displayed are shipped with CQC and are in the
/System/Weather/Weather Channel/ scope of the CQC
image repository.
This widget type has a slightly modified Image tab from the
one discussed in the common attribute tab section above.
In the standard image tab, you get to select an image, but
here the image is selected for you at viewing time. But you
still need to be able to adjust the opacity of the images.
The weather channel images come in four different sizes.
This widget will display from the largest set that will fit within
the boundaries of the weather channel widget you create.
This should work during interface design as well as during
viewing, so you can tell at design time what size it will be.
Note that, if you choose to, you can use other weather image sets. You would do this using the Logo Image widget, not this one. This one
is specialized only for the Weather Channel images that are defined as part of the Weather Channel driver kit and it looks only in that
place for its images. The Logo Image widget allows you to map a value to image names in an arbitrary scope, so it can be pointed at
some User area scope where you’ve imported alternative images.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 109
Web Browser
This widget allows you to embed a web browser into your interfaces. It is effectively Internet Explorer without the menus and frame
window. It can be used to display some fixed resource, such
as a weather radar image, or you can provide command
buttons on the template that allow the user to select
particular URLs to view, by sending SetURL commands to
the widget.
It can be set to auto-refresh every so many minutes, which
is generally used for the fixed resource scenario, to keep
the displayed content up to date, for instance for a weather
radar image or traffic camera, those types of things.
You can also turn on dialog suppression which will, to the
degree supported by IE, prevent any popup ads from
occurring. Be very careful about using any web sites that do
those annoying ‘pop-under’ ads, if you are using a kiosk
style system, since the windows could just accumulate
behind the interface window.
Note that, unlike other widgets, is a separate window
embedded in the interface window. This means that it will
never actually be below any other widget in the z-order,
regardless of where it is in the widget Z-Order. It will always show up on top. It will also show up on top of any popup or popup templates,
which can become an interface design issue.
Commands Accepted:



Navigation. Allows you to send the browser standard web navigation commands like Home, Back, Forward, etc…
SetOpacity. Allows you to modify the opacity of the image dynamically at viewing time. The opacity is a value from 0 to 255
(0xFF), where 0 is fully transparent and 0xFF is fully opaque.
SetURL. Allows you to send a new URL to the browser to display. Note that this can be done in the OnPreload of the containing
template and it will just be stored away as the initial URL to load. So if you are going to dynamically cause something to be
loaded, upon entry to the template, by passing in the URL, do it in the OnPreload for maximum efficiency and the least
redrawing.
Copyright © Charmed Quark Systems, 2005..2014
Interface Development Guide
Page: 110
Web Image
The web browser widget is very useful, but it does have certain drawbacks, as discussed above. The biggest one is that it cannot be
underneath any popup since it is a separate window. It’s also quite heavyweight as well, so using it for something as prosaic as just
displaying an image off of the web is massive overkill. The web image widget allows you to avoid the issues of the web browser widget in
the case of non-animated images (of type JPG, PNG, or BMP.) You can point it at a URL or file based image and it will display that image,
with the usual control provided for placement
and scaling.
This widget comes in field, variable and
static variables. The field and variable based
versions get their URL to display from a field
or global variable, so they are often
convenient when the image is indirectly
available.
For static variants, you can set the image
again at any time using the SetURL
command.
You can set an auto-refresh on the widget,
and it will update the image regularly. Don’t
be abusive here, though the refresh rate can
be set quite fast. For most images you don’t
need to update them really quickly with all of
the overhead that entails.
If the image really is changing constantly,
e.g. a video feed, then turn off caching by
checking “No Cache”. It is a huge waste of
CPU to churn the cache by images that are never going to be accessed again.
If the images are changing more rarely and they come from a set of images that are reused, it’s fine to cache, though that will only happen
if the web server supports it. If the server does allow it to be cached, then it can reduce the overhead since the image may not have to be
downloaded repeatedly.
Typically you would only provide an initial URL for static variants, since the file or variable based ones will immediately overwrite that with
whatever is in the associated field or variable.
If you include username/password info in the URL, Basic or Digest mode authorization challenges from the server will be handled
automatically.
Commands Accepted:

SetURL. Allows you to change the image displayed or to ask that the image be refreshed (if you just re-set the same URL
again.) Only valid for the static variant.
Copyright © Charmed Quark Systems, 2005..2014
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement