Class: cCJSkinFramework

Properties  Events  Methods    Index of Classes

Provides skinning support to an application

Hierarchy

cObject
---cUIObject
------DfComUIObject
---------DfInPlaceComObject
------------DfComActiveXControl
---------------cComActiveXControl
------------------cCJComSkinFramework
---------------------cCJSkinFramework

Library: Windows Application Class Library

Package: cCJSkinFramework.pkg

Description

The cCJSkinFramework class wraps and extends the Codejock Xtreme SkinFramework COM control allowing DataFlex developers to transform the appearance of their application by applying a skin to it. An application can take on a complete new appearance with as little as four lines of code. Skins are applied by selecting a skin file.

You should refer to the Skinning Windows Applications for an overview of the skinning framework. The Class Reference will provide you with syntactical and usage information about the skinning class.

Expected Usage

Application skinning is supported by creating a single desktop skinning object. If a skin file (psSkinFile) and a skin section (psSkinIni) is defined inside of your skin object, the skin/section will be applied to all visual objects in your application.

The skinning object normally requires that a cApplication object be defined first. We recommend that the skinning object be located directly below the application object.

// first create a single application object
Object oApplication is a cApplication
   :
End_Object

// then create a single SkinFramework object
Object oSkin is a cCJSkinFramework
    Set psSkinFile to "WinXP.Luna.cjstyles"
    Set psSkinIni  to "NormalHomeStead.ini"
End_Object

Changing Skins at Runtime

The skin object can also be used to change skins dynamically at runtime. This is accomplished by changing the psSkinFile and psSkinIni property values and then calling ApplySkin. If you use this technique you will probably be doing this within some other object.

Procedure SetANewSkin String sFile String sIni
    Set psSkinFile of ghoSkinFramework to sFile
    Set psSkinIni  of ghoSkinFramework to sIni
    Send ApplySkin of ghoSkinFramework
End_procedure

The ghoSkinFramework Global Handle

The application framework maintains a global handle named ghoSkinFramework. This handle contains the object ID of the skin object. It will be 0 if the skin object does not exist. This can be used by other parts of your program to communicate with the skin object. It can also be used to test if a skin object exists.

Location of Skin Files

The application framework expects skins files to be placed in your workspace's programs directory. When psSkinFile is defined with a relative name, which is recommended, the file will be located relative to the default skin directory. This is simplest way to work with skin files. If you want a skin file to be available to an application, copy it to the workspace programs directory. You can then access that file by assigning its relative name to psSkinFile.

The SkinPath function returns to location of the skin file path.

The SkinQFile function converts a relative skin file name to a qualified name.

Loading and Saving Skin Application Preferences

If you allow your users to select their own skins, you may want to be able to save and load these skin preferences. Setting the pbLoadPreference property to true and setting the application object's pbPreserveEnvironment property to true, enables this capability. The loading and saving of preferences can be customized by augmenting the LoadSkinPreference and SaveSkinPreference methods.

Skinning and the Application Object

The skinning object normally requires that a cApplication object is created and that it is created before the skin object. We recommend that the skinning object be located directly below the application object. The skin object uses the application object to determine where the default directory is located and it uses it to load and save skin preferences. If an application is not available to provide this information an error will be raised.

It is possible to use the skin object without an application object. There are two ways to do this.

1. The application object will not be needed if psSkinFile is set to a fully qualified name and pbLoadPreference is set to false.

-or-

2. The functionality required of the application object can be replaced with your own custom code. The methods, ApplySkin, LoadSkinPreference and SaveSkinPreference all make calls to the application object. You could override these methods and provide an alternative way of performing these functions. If you are going to do this, you will want to study the existing code for these methods.

Skinning and Fonts

If you us skinning, Codejock provides an interface for disabling the applying of font metrics (see ComApplyOptions). When this is disabled, the skin framework will not change the size of fonts. When pbUseWindowsFont is True, the skin framework automatically disables this, allowing Windows to handle the DPI settings. This means that different skins of normal, large, extra-large will now all appear the same size.

Enumerating Skins

If you allow the dynamic selection of skins you will need a way to know what skins files are available and what skins sections are available for each skin file. The function EnumerateSkins will do this for you. It will search a directory for all skin files and then search each skin file for its section names and return an array with all of this information.

The Skin Enumeration View

A special view named SkinEnumeration.vw has been created in the system pkg directory. This view, which can be added to any application that contains a skin object, can be used to display and select skins from the default skin directory.
Adding this view is all that is required to support dynamically changing skins. In addition, it can be used as a template for building your own custom selector. It shows you how to use most of the skinning interfaces such as ghoSkinFramework, EnumerateSkins, ApplySkin, psSkinFile and psSkinIni.

Skinning Custom Controls

The skin framework class requires that all non-standard windows classes be mapped to known windows classes. The non-standard classes are then skinned using the rules from the known windows classes. All of the DataFlex window classes are mapped within a private event named OnAddDFWindowClasses. In most cases, this provides all class mappings required to support skinning.
If you are using custom windows classes in your application, most likely Active/X classes, you are going to need to apply this mapping yourself. This mapping should be placed inside of OnAddCustomWindowClasses. Refer to this event's documentation for more detailed information about mapping custom controls.

Client Area Sizing

When skins are applied, client area sizing will be maintained if the dialog's pbSizeToClientArea property is set true. By default, skinned views and modal-panels will maintain their client area size. This makes your dialogs look much better with skins and it also allows you to design your views without needing to worry about what kind of skin will be applied to it.