13.2 - Conventions

Table of Contents

• 13.2.1 Include Files
• 13.2.2 Namespaces
• 13.2.3 Naming Conventions

This section describes the conventions used in the GUI APIfor including files and using namespaces.

13.2.1 Include Files

All header files include the directory path relative to the include directory. For example, the file ./include/makVrv/DtDe.h is included using the include line

#include <makVrv/DtDe.h>

The forward slash is used to ensure cross-platform compatibility. The convention is also followed by OpenSceneGraph and Boost.

13.2.2 Namespaces

All GUI APIclasses are in the makVrv namespace. When referring to a class in a header file, you must specify the namespace.

To predeclare a class in a header file, use the following syntax:

namespace makVrv
{
   Class DtDe;
}

To use a class in a header file, use the following syntax:

class Test
{
   void doSomething(makVrv::DtDe& de);
};

When writing code in a source file, either specify the namespace with the type or use the using namespace declaration, as follows:

void Test::doSomething(makVrv::DtDe& de) { … }

or:

using namespace makVrv;
void Test::doSomething(DtDe& de) { … }

Note

Never use the using namespace declaration in header files. This will leak the namespace into all files that use that header and potentially cause irresolvable naming conflicts.

Most libraries have a secondary namespace that is used when there are duplicate names, such as the standard init() functions, or in the protocol-specific libraries when they share the same source code. The name of the secondary namespace matches the name of the library.

For example, vrvCoreQt has the secondary namespace vrvCoreQt, which has the library's init() function. To initialize the vrvCoreQt library, use the following code:

void init(makVrv::DtDe& de)
{
   // Initialize the Qt library.
   makVrv::vrvCoreQt::init(de);
}

Note

You must initialize vrvCoreQt if you are building an application that links to it or a plug-in that depends on it.

13.2.3 Naming Conventions

The GUI APIfollows the standard MAK policy of prefixing all classes with "Dt".

All functions, variables, and enumerations are inside classes. Subtypes and enumerations do not get a leading Dt. All class member variables start with the word "my". All class static variables start with the word "the".

The GUI APIuses the following conventions for naming functions:

• Functions that set the internal state of an object start with the word "set", for example:

  void setSimulationTime(double);

• Functions that return a value through a passed reference start with the word "get":

  void getLocation( double &x, double &y, double& z ) const;

• Functions that return a valid state value in the return type use the name of the value without any qualifying verb, for example:

  double simulationTime() const;

• Functions that return an object that may not be valid start with the word "find", for example:

  DtChannel* findChannel(const std::string&);

  The use of find is to encourage testing the validity of a variable that might be invalid. Functions that return potentially invalid variables through references and return a boolean can also use the word find.

• Functions that delete or destroy an object contain the word "destroy", for example:

  destroyModelDefinition( const DtModelDefinition&)

• Functions that remove an object from another object's internal management contain the word "remove", for example:

  removeModel(makVrv::DtModelDriver*);

  This may assume a transfer of ownership if the second object was the sole manager of the first object.

• Most signals that are based on Boost start with the prefix "signal_". Signals that occur before an event contain the words ToBe and then the event, for example:

  signal_terrainPatchToBeDeleted

Note

There are some intentional exceptions to these conventions, usually to improve clarity of the code.

[<< VR-Forces Toolkit Libraries] [Home] [Top of Page] [The Qt Toolkit >>]