C API Functions

## 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.

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