Vvidget Code Reference Manual

Vvidget Code > Common Keys > Templates

Any attribute not defined by a Dictionary entry is defined by the contents of a template, which is a Vvidget Builder document. Those documents are located in the PVS (Peer Visual State) framework's resource directory located at:

/Library/Frameworks/Vvidget_PVS.framework/Resources/English.lproj/templates

If you use the Vvidget Code Embedded frameworks then those templates are located within your own application at:

<your app bundle path>/Contents/Frameworks/Vvidget_PVS.framework/Resources/English.lproj/templates

You can modify those templates by double clicking them and editing them in Vvidget Builder. That will modify the default template configuration for each graph type. If you do that then you should copy the entire Vvidget Embedded Frameworks directory to a location of your choosing, link against that and copy that into your application using a copy build phase as described by the Cocoa Programming Tutorial. That way you will not need to edit the stock Vvidget directory directly. However, using a templates key, as described next, is probably a better choice.

The best prescription for using custom templates is to use the templates key and define a path within your own application bundle's resource folder that contains templates. The easiest way to make your own templates is to copy the directory:

/Library/Frameworks/Vvidget_PVS.framework/Resources/English.lproj/templates

into the directory of your Xcode project, add that to your project and refer to that template directory for your needs by assigning the templates key with a value of that path. Note that the template document names are fixed, you can not change them. However, you may have multiple template directories to make graphs of the same type appear to have different template definitions.

As mentioned before, the templates are Vvidget Builder documents and can be altered like any other document. You can add graphics, change fonts and colors, etc. but one thing you should not do is remove any graphic that exists by default in the template. You must also not change the widget name of graphics in the template.

When you modify the template then the modifications affect all dynamic graphics of that type. For example, you can modify the color table for a Pie Chart in which case all pie charts referring to that templates directory will conform to the new color table scheme. In that way you can set up an application that has a color scheme consistent with your own company's guidelines, for example, and also make many different guideline specifications using different custom templates directories.

Notice that there are two types of templates:

• Base Template: The base template forms the basis of the static graphics. For example, it might contain a graph. You can modify any attribute of the base template; but, if needed, the attributes will be modified in order to satisfy the dynamic attributes of a dictionary.

• Color Table Template: The color table template form the basis of the colors that vary with data index, for example line color or pie wedge color. The color attribute is extracted from the fill color of the rectangles in the color table template.

So, as you see: Vvidget Code uses a dictionary to define dynamic components of a graph description and then also uses templates, as constructed by a GUI tool, to define static components. Or, to look at it another way: A template is used to define hard to comprehend visual attributes and those attributes are easily comprehended via a GUI tool. A dictionary is used to define numeric and string attributes that are easy to quantify within a simple textual encoding. The two combined form the output of Vvidget Code. Really the best of both worlds.

Template Folder

The template folder contains all of the template documents corresponding to each base and color table template type. The listing below shows the stock template folder.

The definitions of each template is given in the corresponding Dictionary section. If you want a custom template for a graph type then your task is to add a template directory within your own project and copy the appropriate template as listed above and defined in the corresponding dictionary description to your project's template directory.

As an example, to customize a line graph you will need to copy the PVST_Line_Graph.book template. For the most part, the template to chose is encoded into the template name and there isn't too much guess work. An example of the use of templates is given by the SimpleLineGraph project, which is available as a Vvidget Code example project and also as a link at the end of the Cocoa Programming Tutorial.