OCAF Browser
General principles
Any Open CASCADE document consists of an Application Data Framework
including a structured set of labels
and attributes. Labels are interdependent
(child label depends on its father) and form a directed tree-type graph
. Each label has a name - this is a unique list of numbers, separated
by a colon ( : ), where the last number is a tag of this label and the
rest is a name of the father label. Thus, a root label with the name "0"
will have, for example, children with names "0:1" and "0:3".
A label contains a set of attributes that are universal data containers.
Each attribute has a type, such as: Integer, Real, Name, Reference, etc.
A label can contain any number of attributes with different types.
OCAF Browser represents the
Application Data Framework tree with its labels, attributes and stored
data. For example, see Picture 1, showing a part of the application structure.
Picture 1.
The picture corresponds to the OCAF Browser window. The document tree structure is shown on the white background: opened folders correspond to labels, icons with an "A" symbol correspond to attributes (or "NS" - named shape attributes). Each entity has a description: its label always has a name and attributes with type name. The list of entities under each label is sorted in the following order: first, attributes of this label, then child labels, which are sorted according to their tags.
Browser functionality
Each folder (corresponding to a label) can be opened or closed
by clicking on the triangle switch near the folder icon. If the folder
is closed, all attributes and children of this label will be hidden (
see, for example, label 0:1:1 in Picture 1). In this way, user can close
unused folders and free the browser window from clutter. If there is not
enough room in the window to view the tree completely, the user can scroll
tree information with the right and bottom scroll bars.
The OCAF Browser window contains the following buttons and
graphical elements:
The "data level"/"first level"/"all levels" combo box manages folders. The "data level" button closes all folders except those labeled "0:1:3:2" and their children. The "first level" button closes all folders except those labeled "0:1" and their children . The "all levels" button opens all folders.
The "attribute"/"attribute list"/"hide attribute" combo box defines the style of attribute representation. If "attribute list" is active, attributes are collected within the corresponding label subfolder, which contains a list of attributes and can be opened as a label folder (it is closed by default - see Picture 3). If "hide attribute" is active, no attributes are shown in the tree.
The filter input line allows making a rapid search of the tree or hiding unused elements: only attributes and labels containing text from the filter string are shown.
The "NS tree" check box reveals the detailed representation of named shapes (see Picture 3). If "NS tree" is on, each named shape attribute can be opened as a folder (see the named shape representation description below).
When the "Description" check box is "on", it rebuilds the button framework and appends next items (see Picture 2):
The "Detailed" check box controls any special descriptions from the displayed tree. If it is "off", these descriptions are hidden.
The special text window gives the user full information about items selected in the tree; this includes the address of the variable and full information about standard attributes and labels.
Picture 2. "Description" mode is on, "Detailed" mode is off, filter string is "Tr".
The "Update" button updates tree contents. This button is necessary because the browser does not update the displayed tree when the document tree is changed.
The "Close" button closes the browser window. The user needs to call the browser again to display the browser window. Only one browser window can be shown at a time.
Picture 3. "Attribute list" and "NS tree" modes are on.
The OCAF Browser has another special functions:
When the user double clicks on the label node, this label and all its sub-labels (sub-lists) take the opened state.
If user double clicks on the TNaming_NamedShape or TPrsStd_AISPresentation attribute, the browser displays the corresponding object in the current document viewer in magenta or erases it if the object was already displayed (for a named shape it creates or removes the new TPrsStd_AISPresentation attribute at the same label).
If the user double clicks on the shape of the named shape attribute ("NS tree" mode is on), this shape will be stored to the "db_shape.brep" file of the current directory in the standard brep (boundaries representation) format.
Some invalid (by the common intendment) attributes (named shape, which refers to the null attribute, for an example) are displayed in red.
Description of standard attributes
Common attributes can be described in greater detail in the tree text string:
TDataStd_Constraint: type of constraint, dimension and set of constrained shape labels.
TDataStd_TreeNode: labels of father, previous, next and first branches.
TDataStd_Name: contained string. If a label contains this attribute, the label also has this string in its description line.
TDataStd_Comment: contained string.
TDataStd_UAttribute: contained GUID - string representation.
TDataStd_PatternStd: contained GUID - string representation.
TDataStd_Integer: integer value.
TDataStd_IntegerArray: lower and upper indexes.
TDataStd_Real: real value.
TDataStd_RealArray: lower and upper indexes.
TDataStd_Expression: expression string.
TDataStd_Relation: relation string.
TDataStd_Position: coordinates.
TPrsStd_AISPresentation: GUID (Global Universal IDentifier) of the corresponding diver of presentation. The description of this attribute is gray if this presentation is hidden.
TPrsStd_AISViewer: displays "(Attached)", if it has an interactive context.
TDocStd_Owner: storage format of document.
TDocStd_XLink: label and document entries.
TNaming_NamedShape: shape type, named shape evolution and list of labels, which contain modifications of this shape. If the new shape is reversed, then color of attribute text is light gray. Also, if the mode "NS tree" is on this attribute has the following sub-items (see Picture 3):
First-level sub-items are new TopoDS_Shapes of the named shape (shape type, label of the corresponding named shape, address of the TShape)
Sub-items of this shape are all of this vertex coordinates and the list of old TopoDS_Shapes of the named shape (shape type, label of the corresponding named shape, address of the TShape)
TNaming_Name: name type and labels, which contain arguments of this name (named shape attributes).
TFunction_Function: string representation of the GUID of the function.
TDF_TagSource: integer value.
TDF_Reference: name of referenced label.
Installation and setting
OCAF Browser is written in C++ language and uses one of three graphic tool kits:
Tcl
The Tcl OCAF Browser is available within Draw Test Harness (TCAF and XDEDRAW executables).
To activate it, use the following sequence:
Launch TCAF or XDEDRAW executables
Draw> source $env(CSF_XCAFDefaults)/dftree.tcl
Draw> NewDoc document
Draw> DFBrowse <document>
Tcl OCAF Browser may be chosen for Windows, Linux and Solaris OS.
FLTK (v. 1.0.11 see Picture 2 - browser using FLTK)
QT (v.4.2.3 see Picture 1 and Picture 3 - browser using QT)
FLTK and QT OCAF Browser is avaliable for Windows only.
This program uses a multi-thread mechanism, which must be supported by the user's OS.
User may use DebugBrowser.hxx include file to compile application: to start OCAF Browser call DebugBrowser::DFBrowser(Handle(TDocStd_Document)theDocument) method with the browsed OCAF document handle as an argument.
Only one browser can be started for one application. If OCAF Browser window is closed, the user could call this method again.
To use the OCAF Browser in applications, you must load DFBrowser library. Also it is
neccessary to load fltk library for FLTK or QT library for QT to use OCAF Browser in an application.
Remarks:
QT OCAF Browser is integrated to the MFC OCAF sample
FLTK and QT OCAF Browser can be loaded in Draw by "DFBrowser DocName" command. This command is added only if PATH environment variable on Windows platform contains a path to DFBrowser.dll library. This variable should also contain a path to FLTK or QT graphic library, whose graphic library should be used depending on the version of DebugBrowser (FLTK or QT accordingly).