C API Functions

prevnext

udbEntityDraw


Description

Create a graphic view of the specified entity in a file.

The kind of graphic views available are dependent on the language and the kind of entity specified. For example, a function entity may have view kinds of "Invocation", "Callby", "Declaration" and "Declaration File".

Graphical view options may optionally be specified as a name and value pair. These options are also dependent on the language and the kind of view specified. For example, the Callby view of a function could optionally show parameters as well as set the font size used, among others.

Note: The graphic views will be changed dramatically before the final release of Understand version 1.4. It's very likely the next generation drawing mechanism will not use this function, but will have a variety of functions that provide more direct support of customizing the graphic drawings.

Syntax

 #include "udb/udb.h"
 UdbStatus udbEntityDraw(char *view, 
                        UdbEntity entity, 
                        char *opts, 
                         char *file)

Arguments

Argument description
char * view Specify the kind of graphic view to draw. Non-allocated. The kind of views available depend on the language and the kind of entity specified. A list of the available view kinds for each language follows.
UdbEntity entity Specify the entity to draw.
char * opts Specify NULL or a string of drawing options. Non-allocated. The format of the options string is "name=value". Multiple options are separated with a semicolon. The valid names and values are the same as those that appear in the Understand Options menus. They may be abbreviated to any unique prefix of their full names. A the list of possible option names and their values for each language follows.
Additionally, the special option 'font' may be specified. Its value must be the path to a truetype font (.ttf).
char *file Specify the output file name (.png or .jpg only). Non-allocated.

The View Kinds are the same as those supported in Understand. Following is the list of supported view kinds for each language.
Ada View Kinds C view kinds Fortran View Kinds
Callby
Child Lib Units
Declaration
Declaration Tree
Declared In
Instantiated From
Instantiations
Invocation
Parent Declaration
Parent Lib Unit
Type Derived From
Type Tree
With
Withby
Base Classes
Callby
Declaration
Declaration File
Declaration Type
Derived Classes
Include
Includeby
Invocation
Parent Declaration
Return Type
Callby
Declaration
Declaration File
Include
Includeby
Invocation

The drawing options may be used to specify parameters used to generate the graphics. The format of the options string is "name=value". Multiple options are separated with a semicolon. The valid names and values are the same as those that appear in the Understand Options menus. They may be abbreviated to any unique prefix of their full names. An example options specification:

     "layout=cross; scale=14"

Not all options are available for all graphical views. The following table lists all possible options and their values and notes to which language they are applicable:

Graphic drawing options option values Appplicable language(s)
Base classes on (default)
off
C
Called by on (default)
off
Ada, C, Fortran
Components on
off (default)
Ada
Derived classes on (default)
off
C
Function pointer on (default)
off
C
Includes on (default)
off
C
Intrinsic on (default)
off
Fortran
Invocations on (default)
off
Ada, C, Fortran
Layout crossing
non-crossing (default)
Ada, C, Fortran
Level all levels (default)
1 level
2 levels
3 levels
4 levels
5 levels
Ada, C, Fortran
Name shortname (default)
fullname
Ada, C
Parameters on
off (default)
Ada, C, Fortran
Private on (default) off C
Protected on (default) off C
Public on (default)
off
C
Scale 14pt
12pt
10pt (default)
8pt
5pt
2pt
Ada, C, Fortran
Static on (default)
off
C
Text no truncate
truncate short
truncate medium
truncate long
wrap short
wrap medium
wrap long (default)
Ada, C, Fortran
Typetext on (default)
off
C, Fortran
Unresolved on (default)
off
C, Fortran
Withs on (default)
off
Ada
Withed by on (default) off Ada

In addition to the Understand name/value pairs listed above, the special option 'font' may also be specified (for any language). Its value must be the path to a truetype font (.ttf).

  "font=c:\winnt\fonts\times.ttf"

Return Values

Return values description
Udb_statusDrawNoFont No suitable font can be found.
Udb_statusDrawNoImage No valid image view is defined or the specified entity does not have a view of the specified kind.
Udb_statusDrawTooBig The selected view is too large. Note the jpg format does not support a dimension larger than 64K
Udb_statusDrawUnableCreateFile Unable to create or open file.
Udb_statusDrawUnsupportedFile File type requested is not supported. Specify only .png or .jpg.

Example Usage

 status = udbEntityDraw ("Callby", 
                        funtionEntity, 
                        "scale=14; level=1",
                         "callby.png");

See Also

Additional graphics functions will be available in the near future.

prevnext


Scientific Toolworks, Inc.
http://www.scitools.com
Voice: (802) 763-2995
Fax: (802) 763-3066
support@scitools.com
sales@scitools.com