Basic Graphics Tutorial

This chapter contains tutorials that deal with basic graphics development in the Dynamic Markup Language. You will need to have read the introductory chapter before continuing.

Opening a Graphics Region

In this first example we will show you how to open a graphics region suitable for drawing purposes. This is initially achieved by using the <embed> tag to tell the browser to create a drawable area for the plugin. The width and height attributes of the embed tag are used to declare the size of the area. The following tag shows how to declare a drawable area of 200x100 pixels:

  <embed type="application/x-dml" width="200" height="100" src="filename.html"
    pluginspage="http://www.rocklyte.com/dml/plugin.html">

When the DML plugin processes the embed tag, it will automatically create a Render object of the same size and give it the standard name of "SystemDisplay". For now, the plugin will be invisible until we initialise some graphical objects to the SystemDisplay area. Lets start by drawing a simple box with a text message in the center. The following code illustrates exactly how to associate DML graphics instructions with an embed tag:

  <embed type="application/x-dml" width="200" height="100" src="tutorials_graphics.html"
    pluginspage="http://www.rocklyte.com/dml/plugin.html" procedure="Example1">

  <dml procedure="Example1">
    <box border="255,0,0" thickness="3" colour="#000000"/>
    <text colour="#ffffff" align="center" face="arial:12"
      string="[systemdisplay.width]x[systemdisplay.height]"/>
  </dml>

This is what the result looks like when the browser executes it:

An alternative to specifying pixel dimensions for the graphics area is to use percentages. This can be useful if you want to use an entire browser window or table area for embedding DML code. Specifying a percentage based value is simple - just use the % symbol after the numeric value.

Advanced Developers: Due to web browser restrictions, it is not possible to 'legally' resize or move an embedded graphics area after it has been created. If you want to risk it anyway, you can try and use the Move and Resize actions on the SystemDisplay object to alter the graphics area when you need to. Use of actions is discussed in a later chapter.

Drawing Graphics

In the previous example we used a box and a text string to put some simple graphics in our embedded area. We did this by using two simple commands - box and text. As you would expect, DML supports a number of graphical commands so that you can build all kinds of custom images to suit your requirements. Even more importantly, each graphic that you create is object based, which means that you can make real-time adjustments to them after they have been created. Here is a list of graphical objects that you can use for drawing purposes:

Object Description

Arrow Draws basic arrow graphics in various directions.

Box Draws boxes, rectangles and squares, filled or unfilled with optional borders and highlighting.

Clock Draws a digital clock that automatically updates itself as the time changes.

Ellipse Draws filled and unfilled ellipses and circles.

Gradient Draws colour gradients in horizontal, vertical and diagonal directions.

Image Used for loading and drawing image files, supports tile and stretch features.

Line Draws a coloured line from one point to another.

Text Draws text string(s) using a selected font and point size. Also provides editing capabillities.

To read advanced information on these commands, click on the links to jump straight to the class manuals, or retrieve them from the downloads page.

All drawable classes adhere to the same naming standards and behaviour when it comes to setting basic requirements like position, size, colours, font details and so forth. For instance, to set the colour of a box, arrow, line or ellipse you would set the colour attribute. To set a position, you would set the x and y attributes. In most cases, names and behaviours are very predictable, so you should find that you only need to check the manuals occasionally.

In this next example we will show you how to create the graphics for a button gadget. To do this we need to use the two graphics objects that were demonstrated previously: Box and Text. The box will need to have a raised surface to give it that 'clickable' effect and we'll need to put a text string in the middle to tell the user what the button does. To create the box, all we need to do is specify the border colours (highlight and shadow), the background colour and use the 'raised' parameter for the 3D effect. For the text, we need to specify the colour, the alignment to center the text, the font that we want to use and finally the string to print in the middle. This is what it looks like when we write the DML code:

  <dml procedure="Example2">
    <box highlight="230,230,230" shadow="60,60,60" colour="180,180,180" raised/>
    <text colour="#000000" align="center" face="arial:12" string="Button"/>
  </dml>

This is what it looks like in your browser:

Simple isn't it? So far, our button is not interactive, i.e. it will not respond when you click on it. We'll look at making our button interactive as we continue on with our tutorials. Just for fun, you could also try using other graphical commands to change the background of the button, e.g. a gradient could be used for a gradual change in background colour, or an image could be used as a background wallpaper. You have complete artistic control over what your graphics should look like - don't let us restrict you!

On A Colourinary Note

You may haved noticed by now that we have been using two different types of strings when specifying colour values. One is the "Red, Green, Blue" format and the second is "#RRGGBB". A colour of white in the first instance would be specified as "255,255,255", while in the second instance we would write it in hexadecimal as "#FFFFFF". The format that you wish to use is entirely your own choice - there is no preferred format and you can mix and match as you please. Generally it is much easier to read colours in decimal format, but for simple colours like black and white, writing in hex is quicker and just as readable.

Graphical Frames and Animation

In order to allow greater control over graphics presentation in DML, rendered areas can be organised into frames that can be switched in and out of view at any time. The technique of arranging graphics into frames can be used for a variety of purposes, and has the advantage of not incurring any speed penalties when changing graphics. This gives us massive potential in two particular areas: Animation and user interaction.

Imagine that you want to display an area of text that needs to catch the user's attention. An easy way to do this would be to animate the message in bold text and flash the message on and off. Like this for instance:

Did that get your attention? Don't worry - your browser isn't about to blow up. To achieve this effect we used an animation tag, which does the frame switching for us. Creating a functional animation object is as simple as placing one inside the render object that contains the frames that you want to animate. The animation class accepts arguments to define the speed of the animation, e.g. speed="1/25" to animate at 25 frames per second. The length of the animation is defined by the framecount field - when the end of the count is reached, it will repeat from frame #1. Here's the code that we used:

  <dml>
    <animation speed="=1/2" framecount="2"/>
    <box colour="#ffffff"/>
    <text frame="2" colour="#ff0000" face="arial:12" align="center" string="WARNING!"/>
  </dml>

In order to make the text flash on and off, the first frame (#1) will draw a white space because the text object isn't associated with that frame. The second frame will print the warning text, because we programmed the text object to appear in frame 2. Thus by telling the animation object to alternate between frames 1 and 2 at 1/2 second intervals, we get the appearance of flashing red text.

There are other objects that also utilise frames for various uses. For example, using the <movement> tag in conjunction with frames allows a rendered area to change its graphics when the mouse pointer rolls over the rendered area. The <onclick> tag can also change frames when the user clicks on the rendered area, which is useful for buttons and icons. We'll look at this more in the next chapter, User Interaction.