Introduction

Studio (or Crestron Design Studio) is Crestron's official, internally developed, all-in-one application for control systems development, and while it provides a powerful environment for building working solutions for many dealers, there is also a community of Crestron programmers who find the existing tool chain (SIMPL, VTPro) more suitable for their development process. Whilst embracing the Smart Graphics technology and the excellent styling capabilities that 'themes' provide, this second community must still employ Studio for the theme editing capability. At Crestron's March 2014 Masters' Training we were informed that there was currently no plan within Crestron to release a lightweight theme editor (i.e. outside of Studio). While this strategy does promote the use, and eventual transition, to Studio, the overhead of installing Studio simply to manage themes motivated me to develop a standalone product - Theme Creator - to supplement Crestron's existing tools.

Registering your Copy of Theme Creator

Theme Creator is supplied as a single installer, and the functionality available will depend on whether it is registered with a valid licence. The unregistered version will provide some basic demo functionality that will permit you to import Black Gloss 2 to demonstrate theme importing. You will be able to create new themes, but these are limited to saving and compiling no more than 5 styles.

On purchasing one (or more) licences from Ultamation's shop, you will be sent a licence key which should be entered into the registration dialogue found under the Help menu. To aid in support, please enter your name and company name when registering. For multi-licence a single key will be generated, but will permit a multiple number of registrations against that key.

Registrations are limited to the number defined when the key is purchased, so a licence can be freely moved from workstation to workstation as many times as you wish. You must, however, de-register on one machine before re-using the key on another.

Importing an Existing Theme

To get started quickly, the fastest method is to import an existing theme. Under the file menu, select 'Import Theme' which will open the import theme dialogue. To reset the import path to the your 'UserThemes' directory which is where compiled themes are normally stored, presssing the 'Set Default Theme Path' button will set the import directory to your system's location. You can then select the Browse button to open a file dialogue to select the specific theme file you wish to import. Next, select a project working directory for your theme. This is the directory where your theme project folder, using the same name as the imported theme, will be created. Click import to start the process. Imported themes extract all image resources from the compiled theme, but fonts are not extracted, only their references. You will therefore need to either install any dependant fonts on your system, or you can use the Font Management function to replace missing fonts with an alternative.

Creating a New Theme

Another way to get started with a clean slate is to use 'New Theme', also under the file menu. This will create a new, empty theme in your chosen location.

A Note on Theme Project Structure

Theme Creator uses a project file structure for each theme. Under a parent directory which is usually, though not required to be, the same as the theme's 'Name'. Within this directory, a single XML file holds the theme definition (Styles, controls, etc.). This file will have the title of the name of the theme and a '.sgproj' file extension. Any image resources used by the theme are also stored in this directory, under the 'Images' directory. The images directory is cleared when importing a theme, so care should be taken not to import a theme into an existing theme's project folder, unless you intend to remove all the existing graphics assets. Finally, an 'Output' folder is generated when the theme is compiled, and will contain the compiled 'name'.core3_theme file, which will also be copied to the local machine's user generated themes directory for use with VTPro-e or Studio.

Saving Themes

Since the project structure lives on the file system, the theme images are stored within the filesystem under the Images project subdirectory. The working project file is stored as an XML document and should be saved periodically. Pressing Ctrl+S, or selecting 'Save' from the File menu will save the project in its current state.

The 'Save As...' function is more involved as it results in the creation of a new theme project structure. This provides the opportunity to rename a theme (say for changing a version number). The resulting project structure will be contained within a directory of the same name as the theme.

Because a completely new theme structure is created, including copying all images from the existing theme project to the new location, there is a check box to stipulate whether you wish to copy all project images (even if they are not referenced by a style) or only those that are currently assigned to one or more style states.

Because a new structure is created, care should be taken not to try to 'Save As...' into an existing project structure.

Importing Images into a Theme

Images can be added to a project in a number of ways. The 'Import Images...' function found under the File menu can also be invoked using the '+' button on the Project Images window tool bar, or by opening the context menu within the Project Images window (right click on an empty - non-image - area of the window).

A dialogue box will appear allowing you to select one or more image files from the file system. These images (restricted to .png and .jpg filetypes) will then be copied to the current project images subdirectory. If there are any clashes of filename with existing image files you will be asked if you wish to overwrite these files.

Once the files have been imported, the Project Images window will update to show the new images.

An alternative method of importing images into a theme is to use the file manager of the workstation's operating system. When Theme Creator is running, it constantly watches the current project 'Images' subdirectory for changes and will reflect these in the application. So adding an image to the Images folder will cause it to appear in the Project Images window. You can also rename images through the file manager and this will be caught, and updated across the entire theme. The exception is deleting an image - this will NOT remove references to the image in the theme. This is deliberate so that you can remove an image and replace it with an alternative without destroying the integrity of image references within the theme. In contrast to this, delting an image from within the application (via the Project Images window) will warn you if the image is in-use within a style, and if you continue, those referenced style states will also be removed.

Changing Theme Properties

Each theme has a number of properties which aren't associated with any visual aspect of the theme, but play some other role, such as a version number.

Selecting 'Theme Properties...' from the Edit menu allows you to edit some of these items, while others are read-only. Items above the line in the dialogue box are editable, while those below are not.

Program Settings

General program settings can also be found under the Edit menu. The most important setting is letting Theme Creator know the location of your Flex SDK. The Flex SDK is not required for building themes, but is required by the compiler, which is invoked when you elect to compile a theme for use in VTPro-e or Studio.

When this field is empty, Theme Creator will attempt to find a valid Flex SDK installation for you, or you can force this look-up with the 'Auto Detect' button. Alternatively, you can browse to a folder containing the Flex SDK libraries using the Browse button. When Theme Creator believes you have a valid path, it will display a green tick. In the example case, we're using the Flex SDK that is distributed with FlashDevelop (used in developing custom Smart Graphics controls).

Since the Flex SDK is itself dependant upon a Jave runtime, Theme Creator will also attempt to query the installed Java instance and display the resulting version information to you. This allows you to ensure that Theme Creator is 'seeing' the expected verison of Java for use with the Flex SDK.

Refreshing Controls

Theme Creator will build a list of installed Smart Graphics controls at start-up so that you can assign styles from your theme to these controls. During the couse of a normal theme development session, these controls will not change. However, for those creating custom controls with FlashDevelop, if you wish to refresh your controls list - say, after adding a new style target to a control - the 'Refresh Installed Controls' function under the 'Tools' menu will update Theme Creator without the need for a restart.

Managing Fonts

The 'Font Management' tool under the 'Tools' menu provides a way to quickly see which fonts you are using in your theme. Fonts contribute significantly to compiled theme size and consequently memory footprint in your compiled UI projects, and ensuring that you only reference fonts you really need can help to optimise both development time and performance.

The font management window allows you replace font families at a single stroke. Right click on the font family you wish to replace and select 'Replace Font References...'. You will be presented with a font selection dialogue box. Select the font you wish to use as the replacement and all references to the original font family will be replaced with the new font family.

To consolidate font families, simply replace the unwanted family with a family that already exists in the project.

Note:Font files are NOT stored in the project structure, therefore if you chose to share a Theme Creator project with another theme designer, you must ensure they also have the same font families installed on their workstation. This is NOT the same as sharing a compiled theme with a Crestron dealer, CSP or other UI designer, since in these cases they will be using the compiled versions of the fonts from the theme container.

Any font families that are referenced in a theme but not available on the workstation will be flagged with a red thumbs-down. After installing a missing font, Theme Creator should be restarted to pick up the change.

All referenced fonts are compiled into the final theme so that the Smart Graphics platform is able to render the touch panel exactly as it was intended by the theme designer, regardless of what fonts are installed on the target device's native OS. A major factor in the size of a compiled theme is the range of characters or 'glyphs' that are included from the source font file (e.g. Arial.ttf) so it would be wise to limit the glyphs that are compiled into the theme. This can be accomplished by selecting the Unicode ranges that should be included when compiling the font. Currently, the default range is Latin which covers US-ASCII, and the various extensions for European languages, currency symbols etc. We also provide the facility to include Cyrillic, Arabic and Hebrew or a catch all of 'Any' which will include every glyph that the font file provides - this should be used with great care as the resulting compiled font could be extremely large.

Fonts that declare (via the metadata within the .ttf/.otf file) that they don't support a particular range will have that option greyed out and will not be selectable.

Creating a Style

Once a theme project has been created or opened, the Style list window provides the mechanism for creating new styles. Right click on this list to open the context menu and select 'New Style'. This will create a new style object that can then be modified. The style's numeric ID is automatically generated but can be changed via the property inspector. Note: Style ID's must be unique across the theme. Styles can also be created by copying and pasting from an existing style.

Initially, a style will not have any states - this defines it as text only style, and as such, properties such as scaling mode and constraints are not relevant. As style without states has no imagery.

To change the font characteristics of the style, simply select the style from the list and the property inspector will change to reflect the current style and allow editing of these properties.

Adding a State to a Style

To create a style for use in skinning buttons and other controls, you must add one or more image states to the style. First start by opening the style editing document by double clicking on the required style from the Styles List window. Then simply by drag images from the Project Images window onto the lower area of the document window. Each image will create a new state and these can be re-ordered by dragging them up and down. States can be deleted using the Delete key or through the context menu.

Note:Because scaling properites are an attribute of the parent style, state images should all share identical dimensions.

New states will take on the font properties of the parent style but can be overriden via the property inspector when the desired state is selected.

States can be renamed for convenient referencing within VTPro-e and Studio but double clicking on the name to the top left of the state. A state 'reference label' is also shown to the right of the state. Thais label is not part of the style or state, but is a helper to indicate which state 'slot' of a control you are currently editing. For simple controls like a button, this may be as simple as 'Normal', 'Pressed' and 'Active'. For other controls, such as the Media Player Smart Object, which has over one hundred states in some of its styles, the reference label can be a great help in being confident the number and order of states is correct.

You can change the current reference control using the toolbar of the style document. Simply select the control, and then that control's style target, and the reference labels will change to reflect that control.

Changing the Imagery for a State

Once a style has one or more states defined, you may want to replace the imagery used without changing the ordering of states or upsetting existing state properties, such as name or font attributes.

You are able to do this by holding down the CTRL key as you drag and drop project images onto states in the style document window. Simply press the CTRL key before releaseing the left mouse button and the target state become highlighted, rather than the usual "insert" indicator.

If you select and drag across multiple images, the images will be replaced sequentially in the order that they were selected from the project images window. Should you select more images than there are states remaining in the style, then new states will be added to the end of the list as normal.

Modifying Font Properties

Clicking in the top area of the style document will select the parent style properties in the property inspector. Clicking on a state instead select that specific state in the property inspector. From here, all aspects of a font's style can be modified including family (typeface), size (in points), colour (including alpha transparency), weight, style and vertical and horizontal alignment.

Crestron have exposed some other properties in earlier versions of Studio though some of these do not appear to be implemented in the Smart Graphics platform. For this reason, Theme Creator does not currently expose these properties. They include rotation, orientation, anti-aliasing and underlining.

Selecting a Scaling Mode

One of the powerful features of Smart Graphics is the support for varied scaling modes for the imagery of styles. As well as standard stretch and aspect-ratio-locked stretch modes, Smart Graphics also includes a mode called nine-slice. This mode allows you to specify a margin around the image that will not have scaling applied, leaving only the edges and centre of the image to be scaled as the control is resized. This means that a lightweight button or background image can be included in the theme and resized without loss of image quality when the panel is drawn by the target hardware.

When nine-slice mode is selected, 4 properties become active - left, top, right and bottom margin which define, in pixels, the dimensions of the nine-slice.

Setting Scaling Constraints

Although it's unclear how these properties are applied within the Smart Graphics environment, each style can have a set of default and maximum width and height properties defined. These values are then used when displaying the style imagery in the style document window.

Assigning a Style to a Control

Before a style can be used in a project, it must be associated with one or more controls. In addition, a control will often declare more than one style 'target' (i.e. an aspect of the control that can be styled).

In order to assign a style to a control, open the style-target tree for the control you wish to assign styles to, in the Controls Tree window. Select a style and drag it onto the control's style-target. If this is the first style assigned to the control's style-target it will automatically be designated as the default style, however this can be changed though the context menu.

Once assigned to one or more controls, you can see where a style has been assigned by selecting it in the Styles List window and pressing space. This will open the Control Tree view to show all associated style-targets.

Note: The compilation process attempts to make as many optimisations as possible in order to reduce the final compiled theme size. This includes omitting any images, fonts or styles that are not assigned to a control. It is therefore possible to design an entire theme, yet result in a theme without any visible styles in VTPro-e in none of the styles are associated with a control!

Note: Sometimes, it may be desirable to omit a control from a theme, even if a style has been associated with it. You can exclude a control from the compiled output through the context menu of the Control Tree window. As discussed above, this may also result in a style being entirely excluded from the compiled theme.

Merging Controls from Another Theme

There are times when it may be useful to merge controls, and their associated styles into the current project. One example is when Crestron release a new control (such as the Party Mode Smart Object) and update their standard themes to support that new control.

If you have already modified one of the Crestron themes with your own styles, this presents a problem as you would either have to manually add the new styles to your modified theme (and you may not have the graphics assets or be able to identify every style/state) or re-apply all of your previous edits to the new theme.

Another scenario is that you many wish to create a new theme, but re-use some of the styles from some of your earlier work.

The Control Styles Import function allows you to specify another Theme Creator project (which could be a previously imported Crestron theme). You will then be given a list of all controls defined in the project. Select the controls you wish to merge into the project you're currently working on and click "Import". For each selected control, this will then:

• Add the control definition to your theme, if the control doesn't already exist.
• Copy any styles across to the current theme. If style names conflict, the new style will be given a new name (e.g. "New Style" will become "New Style (1)")
• Copy any associated images from the source theme to the current theme. Again, if filenames would conflit, the image will be safely renamed.

Managing Project Images

The Project Images window provides a view into the Images subdirectory of the project, much like a traditional file manager. Currently, images are always ordered alphabetically but they can be filtered dynamically by entering part of the file name in the Project Images toolbar search box.

You can also select to filter images, using the 'Image-' button, to show only those images that have not yet been used in the theme.

The context menu for the images within the Project Images window provides functions for deleting and renaming images. Renaming an image will propogate the change throughout the theme to maintain integrity. Deleting an image will first check to see if the image is in use. If it is, you will be asked whether you wish to continue, and if you agree, the image and all associated style states will be permenantly removed from the theme.

The other function provided by the context menu is to define which image should be used as the theme's preview image. This will then be indicated by a 'preview' banner over the image. This image does not need to be used elsewhere in the theme.

Compiling a Theme

Creating the final, compiled theme for use with VTPro-e or Studio is as simple as selecting 'Compile...' from the File menu or pressing F12. The compilation process will work through a number of steps to build the various components of the theme and, upon successful completion, the resulting .core3_theme file will be stored in the Output subdirectory of the project structure, and also copied to the workstation's user theme directory, ready for use within VTPro-e.

Following compilation, the target design tool (VTPro-e or Studio) will need to be restarted in order to recognise the new theme.

Archive/Unarchive

These functions are not yet implemented. This feature will simply provide a convenient mechanism for packaging/unpacking Theme Creator projects to allow simple archival or sharing with other developers or team members. Please refer to the roadmap for more details.

Release Notes

1.20

• update to licensing - server requires client update

1.16.1888.0

• Overhaul of font management which fixes a number of issues reading font meta-data

1.14.1880.0

• Fixed a bug in the registration service following changes to the SSL authority
• No longer allows themes to be created or saved-as with names that begin with a number, or contain special characters.
• Catches exception when the email client fails to open.
• Can now rename themes when importing them, and checks for invalid characters in the new name.

1.12.1835.0

• Fixed bug where importing themes, which was compiled with newer versions of the java sdk, caused image loading problem.
• Compiler now displays warning if the theme is not compiling correctly.
• Added feature which highlights all open styles, within the styles window, with a light orange.
• Added feature which highlights the currently selected style, within the styles window, with deep orange.
• Added feature which allows the deletion of multiple styles at the same time.
• Fixed bug where opening a style and resizing the preview could cause the program to crash.
• Fixed bug where deleting custom control caused exception.
• Fixed bug where imported theme, that has associated style does not have a default style.
• Corrected the window header background from transparent to white.
• Added ability when deleting multiple styles at once, to cancel and apply yes to all.

1.11.1453.0

• Copy and pasting styles within style's window now focuses on newly created style.
• Improved clickable area for image window. Right clicking the area around an image in the image window now brings up the options for that image.
• Added quick key functions, matching right click pop up menu.
• Added feature to open control menu folder when draging style over folder and hoving for 2 seconds.
• Fixed bug where properties menu was not updating when changing focus from properties window to style window.
• Fixed bug where dialog window could be larger than screen size.
• Improved drag and drop feature.
• Fixed a bug where saving images into a project while open within theme creator caused exceptions.
• Corrected a bug where 9 slice adorners were not showing the correct values.
• Fixed a bug where 9 slice values were not updating when 9 slice adorners are dragged.
• Fixed a bug where replacing 9 slice image with a smaller image than the values of the nine slice, could cause the nine slice values to go out of bounds within properties menu.
• corrected bug where bottom left 9 slice adorner was not showing the correct icon.

1.10.1098.0

• Fixed a bug where state font attributes were not inheriting from the parent style on import
• Fixed a bug where replacing a font in the font utilities would nullify the state font attribute (resulting in an empty font selector)

1.9.1080.0

• Fixed a bug where braces in image filenames would cause the compile to fail
• Added feature to allow Java heap space to be spcified for larger theme compiles
• Added support for CJK Unicode ranges for fonts
• Corrected a bug that mis-represented Cyrillic support in TrueType Fonts
• Added canned "Crestron International" Unicode range selection for font compilation
• Changed the font management unicode range selection show, rather than restrict which ranges are advertised - these are often wrong!
• Fixed a bug introduced with Windows 10 updates from Windows 8.1 where fonts that existed in the registery didn't exist as files - Thanks Microsoft.

1.8.1050.0

• Fixed a Mac/Windows compatibility issue which caused an exception on loading project images with resource forks (thanks to Terry Swait)
• Controls list will now flag theme controls that don't match the installed control structure
• Added an option to update out-of-sync theme controls with their installed counterparts, plus warnings if data will be lost!
• Added warnings for missing images and included the "missing image placeholder" to the distribution build
• Added Flex SDK version info to the settings box to assist in compilation configuration
• Tools tips added to control tree and styles list to explain iconography and inconsistent control structures (thanks to Jared West)
• Refactored "installed controls reference"
• Added "Expert Mode" to provide increased information in certain areas (so far only: Style entity names shown in Control Tree View)

1.7.996.0

• Fixed minor bug where changing the refernence control wouldn't update the style target references
• Selecting a control or control style target from the control tree will automatically switch the style document reference to that control
• Fixed an issue where beta styles in Crestron themes would not appear following release of the control (e.g. Subpage Reference List)
• Added optional warning for orphaned styles, and warning indicator for unassigned styles
• Added optional warning for controls without assigned styles
• Complete re-write of the property inspector
  • Removed a dependency on a 3rd party library that was causing a number of exceptions
  • More control over the property grid representations of each object
  • New colour picker (v1 - it will get better!)
  • Add Image properties (read only) to the property inspector
  • Add Control properties (read only) to the property inspector
• Added feature to highlight all styles where a selected image is in use
• Updated the XML control definitions to include additonal controls and icons styles recently added
• Fixed a typo on compile dialogue - not VTPro-3 ;)
• Added a count of style states to the style list pane, this can be used to sort
• Added MRU list feature
• Added a manual 'Refresh' to the Project Images window
• Reversed changes to ProjectImage Filter as it broke a LOT of stuff (threading issues). Needs to be revisited.
• Additional protection around trying to open "missing" projects
• Fixed a bug introduced in 1.6 where the unsued images filter was broken
• Reduced installation download by 25%

1.6.693.0

• Replacing a font, which is currently the project default, in font management will now ask if you want to update the default project font
• Moved font enumeration to the task threadpool to improve startup performance
• Modified the search filter on the project images window to improve performance
• Updated program settings to allow for greater customisation (dialog box questions, etc.)
• Main window position is now persisted across program starts, and recovers from opening on a non-existant secondary monitor
• Added an option to force styles to be included in a compiled theme, even if they aren't associated with a control
• Fixed a bug that stopped a registered licence from being deregistered
• Added code to allow an installation to run even if [Drive]:\ProgramData\Crestron\Core3\UserCtrls\controls doesn't exist. The Crestron tools create this normally.

1.5.602.0

• Added templating feature, with built-in templates for Crestron standard style IDs
• Fixed a bug where the preview image wasn't being extracted on theme import
• Fixed a bug where Save As with 'referenced images only' might throw an exception on a missing preview image
• Added check to ask if you want to save the theme on compile (if it's not already saved)
• Fixed a bug where the scaling type was lost when copying styles
• Fixed an issue where the compiled theme could not be deployed if the UserThemes directory was missing
• Fixed a fatal crash on start up if the previous project had been moved or deleted
• Fixed an issue where the preview image wasn't being flagged as "used"
• Added default project settings for font styles which are applied to all new styles
• Added feature to delete unused images
• Added version checks to protect project integrity and prompt for updates
• Fixed the control styles merge function so that style IDs are preserved if not already in use in the target theme

1.4.503.0

• Added mechanism to allow drag/drop of images to replace existing state imagery, rather than creating new states.
• Added mechanism to provide merging of controls from another Theme Creator project for easier management of Crestron updates etc.
• Added support for Jpeg image data in themes.
• The Java binary location can now be specified in the Settings dialog to allow precise configuration and avoid PATH problems.
• Duplicate style names are now given a numerical suffix in parenthesis, instead of the "Copy of " prefix previously used.
• The dirty flag is now checked prior to opening a new theme to ensure you get a chance to save any unsaved changes.

1.3.406.0

• First public release
• Added Crestron-endorsed 'fingerprint' to compiled theme output
• Numerous bug fixes
• Updated known-issues list

1.2

• Font support has been completely overhauled. This includes querying the OS for installed fonts, support for the new FontInfo theme entity and rationalisation of Crestron font families and how they may to concrete fonts.
• Font Analysis has become Font Management and the author can now elect which Unicode languages should be supported.
• Various bug fixes to theme loading.

1.1

• Project image enhancements - sorting images, filter by name & in-use
• Further alignment with Crestron theme structure - both output and importing.

1.0

• Initial release for Crestron review.

Development Roadmap

The following items are a on our radar for things we'd like to include in future releases of Theme Creator, or items we've been asked to include by users. They are not in any particular order of priority or implied delivery date.

• Add a tool for comparing two themes ("themeDiff") and merging differences
• Additional unicode range support
• Add auto-save function
• Add caching of intermediate files to speed up incremental compilation.
• Archive/Unarchive Theme Creator projects
• Image transformations - providing fast access to simple image and colour transformations
• Background compilation
• Perform project image filtering in the background so as not to hang the UI
• Control structure comparison tool to check theme consistency
• Please submit any cool ideas to Ultamation!

Licencing

This software is released as a commercial product, and is licenced on a 'per installed seat' basis. To register multiple instances of the product simultaneously on multiple machines requires multiple licences.

The product has been developed using, or with a dependency upon, the following libraries: