Introduction

The GraphEngine is a generic chart rendering library. The primary use will be to generate charts for TikiSheet, but usage could be extended to other features in Tiki and other projects. The library should be working and integrated to TikiSheet by the 1.9 release. This page indicates the development status, decisions and various specification rules. It's written for those using the GraphEngine library (not the user interfaces that will use it) or extending it.

The library aims to be output independant. At the moment, multiple renderers are available:

• GD (PNG, could be used for JPEG and other formats supported by GD)
• PDF (Using PDFLib)
• PostScript (Using PSLib, in PECL)

Other renderers such as SVG and PDF using other libraries can be added without any major changes. Those renderers are planned in a post-1.9 future. To ensure the independance of the renderers, all renderers must extent the GRenderer class and follow the base guidelines and follow the expected behaviors.

GRenderer Specifications

• General Rules
  • Renderer clients only rely on the base interface defined by GRenderer.
  • Methods starting with an underscore are used internally and are not part of the interface.
  • Lengths and positions are given as float values between 0 and 1. The values are proportions of the width or height.
  • Output parameters are given using the style parameters.
  • Coordinates begin from the top-left corner as (0,0)
• Style parameters
  • Renderer-specific.
  • Clients should not make any assumptions concerning the structure.
  • Implementers choose the structure and can modify it at any time (as long as everything still works).
  • Are created by the getStyle( $name ) method. The names are common to all renderers. Implementers are responsible of making sure the styles returned behave properly.
• Text
  • Location is based on left, right and height.
  • Height is the top of the string.
  • In the case of vertical text: height becomes left, left becomes bottom and right becomes top.
  • Alignment and orientation is handled by styles.
  • getTextWidth() and getTextHeight() return values between 0 and 1 to make sure the clients can perform appropriate calculations.
• Shapes
  • Lines use the LineStroke styles.
  • Rectangles can use the LineStroke and FillStroke styles.
  • Pies can use the LineStroke and FillStroke styles.
  • Angles in pies start at 0 RAD, (1,0), or whatever you call that location at the right of the circle.
  • Angles are counter-clockwise.
  • Angles are given in degrees.
  • Radius is a length and will be transformed against the smallest of available width or height. (consider a landscape sheet of paper, height would be used)

Graphics

Feeding Data

TODO

Currently Available Graphics

• PieChartGraphic

About Fake_GRenderer

The Fake_GRenderer class is a decorator class over any kind of renderer. It allows to create a renderer over a portion of the other renderer. The fake renderer is used internally to force methods to draw in specific portions of the graphic without sending 4 position parameters.

For example, the _drawContent() abstract method recieves a renderer as the first argument. The draw() method initialize in Fake_GRenderer to the content area of the graphic after determining the size when title and legend have been positionned. This way, the child classes are totally independant and render their content in a 0 to 1 area, no matter what the real position is.

The renderer could be used by clients to fit multiple different graphics in a same canevas without having to modify any of the graphics being rendered.

The fake renderer forwards the method calls to the real renderer after scaling the positions and adding the offsets. All components are scaled down except the text. Since in all graphic libraries used the fonts have a static size, the size of the font cannot be scaled down. To keep consistency, opposite operations are applied in the calls to getTextWidth() and getTextHeight(). (You dont have to understand this, it magically works)

Tasks remaining

• Unify the data-feeding API
• GridBasedGraphic abstract class
  • Scale managers
  • Grid and Scale rendering
• LayoutManager to modify the default layout parameters
• Various graphics extending the GridBasedGraphic
  • BarStackGraphic
  • MultibarGraphic
  • MultilineGraphic
• Integrate with TikiSheet