Personal tools
You are here: Home / cmgui / Zinc / Writing a zinc application

Writing a zinc application


The following is intended to be a basic guide to writing your own zinc application. If developing under linux you will be able to copy the suggested commands and modify them slightly before runing them at a command prompt. If developing under windows just use your standard methods for making directories, extracting jars, editing files etc.

Note that I assume that you are already familiar with cmgui comfiles. Before writing a zinc application it is usually a good idea to develop a cmgui comfile that does the bare bones of what you want (eg loads up the model). You can then convert that into a zinc application and add a suitable graphical user interface (gui) to allow manipulation of your model. If you have created a cmgui example and added it to the example tree I have a script which automates much of the conversion process. See me for further info.

Set up your environment

  • Make sure you have a recent version of firefox installed on your system
  • Download and install the latest version of the zinc extension for your platform (eg windows or linux)
  • Download and install the latest version of firebug (a useful firefox extension for debugging javascript)
  • Make a directory for your application, eg 'mkdir ~/myapp'
  • Download example_a1.jar to use as a template for your zinc application. Place it in your application directory (eg ~/myapp) and extract it 'jar -xvf example_a1.jar' Check that your myapp directory now contains the subdirectory 'chrome'.
  • From your browser open the xul file for the application and check that it loads, eg 'firefox ~/myapp/chrome/content/example_a1.xul'

Familiarise yourself with the example a1 template

  • The directory structure for your app should be as follows: 'myapp/chrome/content'. The content directory will contain your key files for your zinc application. Note that this structure is used as it allows you to later extend your application and package it for xulrunner so that it can be run as a standalone application, without firefox. To begin with you need only be concerned with the files in the content directory.

  • The key files are:

    • the xul file (this describes your gui layout), for simple pages an html file may suffice
    • the javascript file (this sets up the functionality that is accessed by your gui, eg the code that gets executed when you click on a checkbox, button, slider etc)
    • data files, eg exnode and exelem files (these describe your model)
  • Open up the xul and javscript files and have a read through them

  • Read through the document on Program flow for a zinc application

Modify the xul file

If you do not require any complex gui widgets you can replace your xul file with a plain html file. For an example of how use a plugin wthin html see Html GUIs for zinc applications . For creating more complex guis can be accomplished using xul. Xul is a markup language which can be used to describe the layout of widgets (eg buttons, checkboxes, sliders etc) on a page. Your xul page describes your graphical user interface and hooks them up to functions. Note that the template contains only a few widgets (some check boxes). There are many more widgets available. For example the zinc physiome eye application also uses buttons, radio buttons and sliders while the digitser uses drop down lists. If you open up either of these applications you can then access the View menu and choose 'Page Source' to view the xul file.

To add the widgets you want you will need to learn some basic xul concepts. For the best place to start read Developing GUIs for zinc applications.

Modify the js file

Javascript is the programming language which you will use to implement the functionality you want when various widgets are clicked on. The first few routines in the js file are to do with setting up your zinc application and are described in Program flow for a zinc application. The remainder of the files are functions to be called when the user clicks on a widget. You will need to pick up javascript so that you can write the functions that will run when a widget is clicked.