(c) Innovative Software GmbH, 1990 - 1994, all rights reserved.



	The Object Engineering Workbench for C++ (tm) V1.3

	

	           GETTING STARTED NOTES 
	           =====================



Introduction
============

These notes highlight points about the operation of OEW.  Please 
read them through.  If you have any difficulties, please make 
contact with the support address listed above.



Frequently asked questions
==========================

How do I make a class?
	Click on Edit / New class or
	press "+" button on the toolbar or
	press <crtl> + N on the keyboard.

How do I move a class?
	Hold down the <Ctrl>+ RIGHT Mouse Button and Drag.

How do I make a member?
	Doubleclick on a class
	press the New Slot button
	fill out the dialog and press OK.

How do I make a member fucnction?
	Doubleclick on a class
	press the New Slot button
	choose "Method" as the slottype
	press "More" to enter the design and programming dialog
	fill out the dialogs and press OK.

How do I make an inheritance relationship?
	Drag a line with the left mouse button pressed from one 
	class to another,
	release the button.

How can I remove an inheritance relationship?
	Drag a line with the left mouse button pressed from the 
	superclass to the subclass,
	release the button.

How do I make other relationships?
	Press the ORM button of the Toolbar,
	to call up the Object Relational Modeler.
	The first thing you want to do is call the View/Reformat/Class 
	Hierarchy Menu to make the graph a bit prettier.
	Next Drag a line (Left Mouse Button) to connect two classes and 
	a Edit Relation dialog pops up.
	Choose the type of the relation (In Both Directions) and press OK.

How to get submodels?
	You can collect parts of the whole hierarchie in so-called Views.
	A View is a collection of classes and their relationships. Each class 
	can appear in different views.
	To create a view click on the magnifying class icon on the toolbar and
	define views as described in the online help.



Neat things to test out:
========================

Quick Reference : 	
	A Quick way to get class information.
	Press F5 or Edit/Quick Refrence Menu option
	and enter the name of the object.

ClassList : 
	A List box of classes.
	The toolbar button right of the binoculars or View/Overview Menu option

OverView : 
	A Graphics Overview of the hierarchy.
	The toolbar button of the binoculars or the View/Overview Menu option


The Main Window and the ORM Window
==================================

Both the main window and the ORM window can be open at the 
same time (especially on a big screen).

OEW/ORM is an additional module that adds to the analysis level 
of the workbench.  It does this by displaying member class 
relationships (that is: "has a", "whole/part", "uses", or "contains", 
depending on your terminology), and reference relationships, as 
well as inheritance relationships.  Note that in the Edit 
relationship dialog box you can add your own terminology for 
relationships.  These are called "relationship labels".  The ability 
to name relationships lets you incorporate terminology from the 
methodology of your choice.  This is in keeping with the design 
philosophy of OEW, in not seeking to introduce a new 
methodology, but to support the concepts inherent in existing 
methodologies.  It aims to support the ideas that express meaning 
in a model, and at the same time map these meanings to constructs 
supported by the language.

To concentrate on member class and reference relationships, use 
the ORM window.  To concentrate on inheritance relationships, 
use the main window.

You can have both windows open at the same time.  Classes are 
accessible through the Class dialog box in both windows.  
Double click on the class icon.


Differences between the two windows
===================================

Relationships can be declared in either window.  What varies 
between the two windows is which relationships can be 
displayed and which ones can be declared and defined.  The 
differences can be seen when you compare the following 
tables:

	Main window

		relationship	visible		declaration	definition
		------------	-------		-----------	----------

		inheritance	yes		yes		yes
		member class	no		yes		yes
		reference	no		yes		yes

	ORM window

		relationship	visible		declaration	definition
		------------	-------		-----------	----------

		inheritance	yes		yes		no
		member class	yes		yes		yes
		reference	yes		yes		yes


Importing Source Code
=====================

We find that one of the first things people wish to do with OEW is 
import existing code.  Please be aware of the following:

1.  The parser analyses code for constructs that can be stored in 
the objectbase (classes, data members, member functions and 
datatypes).  Fragments of code that cannot be recognised (for 
example: includes to C function libraries, or some comments) are 
filed in modules. Go EDIT/MODULES to see this code.

2.  It is important to check that the include path in the Import 
from source dialog box is set properly.  For example, if you select 
a source file, make sure there is a path to the directory containing 
the header file.  It is not necessary to set a path to included C 
function libraries.  The include path defaults to the path defined in 
the SET INCLUDE statement (if there is one) in your AUTOEXEC.BAT file.  
It is possible to enter a series of paths in the include path edit field. 
For your first import we suggest to leave the include path edit field 
empty and to select the "execute #includes" option. 

3.  It is not necessary to import a large group of classes to test the 
parser.  We suggest that you choose a small group of classes that 
are representative of the way you work.  You can start by importing the 
header files and after the first view of the model you may import the source 
code too. OEW's purpose is to encourage you to design and program 
applications using C++ as an object-oriented language.  In practice, not 
everything may be 'object-oriented', because of design and time limitations.  
OEW therefore provides modules to incorporate these functional 
elements of the design into the model.

4.  It is a good idea to create (save) an objectbase for a model 
before generating or importing code.  This ensures that the source 
code files are generated into a unique directory. After your final code generation 
you should save the objectbase again to make sure that the date set for the 
objectbase is newer than the source files. The next time you load your model, OEW 
will check if any changes to he source files have occured. This can only work properly 
if only those files have a newer date that are changed manually outside OEW.

5.  You can save a model while working in the dialog boxes by 
using the Shift + F12 key combination.

6.  After an import, it is advisable to check the list of datatypes 
(enumerations and typedefs) added to the built-in types. Select 
Edit datatypes from the Types menu.


Working with Class Libraries
============================

You may wish to import a whole class library, such as the Borland Object 
Windows Library or the Microsoft Foundation Classes to see how OEW works. 
But this is not necessary to write code using the library. There are various 
possibilities in working with class libraries:

1. Class libraries with a code generator

Many class libraries, e.g. for programming the user interface of your 
application, provide an IDE with a C++ code generator. You graphically 
model your user interface and then generate C++ code. This C++ code 
consists of classes which are derived from the classes in the 
library. If you import the generated code (header and source files) using 
the "import all" option you will find the classes you created and the 
library classes they are derived from in your OEW model. You can then 
add functionality to the application by adding slots (data members and
member functions) using OEW. The library classes will not have any
slots unless you set the import path to the include directory of the 
class library. OEW needs the empty library classes to generate the 
inheritance stucture properly. Make sure that the class library 
is included in the right module header schemes.

2. Class libraries without a code generator

Create an empty class for each class of the class library you need. Mark 
these classes as library classes. Than derive your application classes from 
these library classes using the right click popup menu. Proceed as 
described above. 


Rearranging Diagrams
====================

Both diagrams can be rearranged for better presentation and easier 
reading. For more details please refer also to the help topic 
"Mouse Operations".

Inheritance Diagram (class hierarchy)
=====================================

Focus on a class in the class hierarchy and use the Crtl key 
with the right mouse button.  Hold down the button and drag 
the class to its new position, then release the button.  This 
option does not work if you choose to have the Sort classes 
alphabetically option on (see the View menu).

Relationship Diagram (Object Relationship Model)
================================================

Mark a class (single left click), and use the Crtl key with the 
right mouse button.  Hold down the button and drag the class 
to its new position, then release the button.  This diagram is 
based on a grid, the size of which is dependent on the longest 
class name, and the font type and size.  Note that you can 
mark and move more than one class at a time.


Marking Classes
===============

It can be useful for some tasks to work on a number of classes at 
once, for instance moving classes in the relationship diagram, or 
marking classes as library classes.  See the online help topics 
Marking classes and Edit multiple classes.


New Class
=========

There are a number of ways to enter a new class.  See the Add 
new class topic.  In the ORM window, you can position the cursor 
in a selected spot on the background of the window and double 
left click to add a new class.  The new class will be added to the 
diagram at the selected grid position.

Note also that you can enter more than one class at a time by 
separating the class names by commas.

See the Class dialog box help topic for detail on creating a class 
and its attributes and methods.


Import from Objectbase
======================

Once you have created a model, you can reuse classes, instances 
and datatypes in a new model by using the Import from 
objectbase function (on the Edit menu).  Note that you have the 
option to import the associated scheme files as well.


Quick Reference
===============

The quick reference is a browser which you can access with the 
shift+F5 function key while you are in another dialog box, for example, 
in the Class dialog box.  It can be very useful when you are 
working on one class, and you want information about another 
class.


Global File Names
=================

You can set file endings and subdirectories for the source code 
files.


Edit Main Program
=================

You can edit a main program from this option on the Edit menu.


Modules
=======

Each class has a module.  By default there is one module for each 
class.  You can have more than one class in a module.  You can 
enter the Modules dialog box either from the Source menu, or by 
clicking the Filenames button in the Class dialog box and then the 
Modules button.


Container Classes
=================

You can link container classes to 'descriptive tags'.  Container 
classes can be used to manage the cardinality of attributes in 
classes by selecting the related 'descriptive tags' from drop down 
list boxes.  These container classes can be template classes.


Using a Makefile or a Borland project file
==========================================

If you are using the Borland 3.1 compiler, you can choose between 
using a makefile or a project file (see the Options menu).  When 
code is generated either the makefile is generated, or the Borland 
project file is updated. If you have created an individual project 
file once and you switch to the generate makefile option later, 
please change the name of the makefile in the edit global filenames 
dialog box by pressing the default button. Otherwise you will override 
your project file with the makefile. Make sure that the include path 
is set correctly in Borlands IDE.


Views
=====

You can choose subsets of classes and arrange them in separate 
views, in both diagrams.  Views allow you to focus attention on 
aspects of a model.  A class can be in any number of views.  A 
view can be set exclusive, in the Select view dialog box, to isolate 
the classes in the view from the other classes in the model.  When 
a view is selected the name of the view is included in the title bar.


Overview
========

Use the overview to see a complete diagram when it is too large 
to fit on the screen.  The dark area in the miniaturised overview, 
which is the visible section of the diagram, can be moved by 
dragging it with the mouse.


Class List
==========

Use the class list to help with navigation in a large diagram.  
Highlight a class in the list to move it into the visible section of the 
diagram.


Access to Objects in an Objectbase
==================================

Access is based on the level of the user group of the user who 
creates an object.  If another user belongs to a group with a higher 
level, he or she will be allowed access.  Objects to which a user 
does not have access are displayed in grey.  The user can browse 
them, but not make any changes.  You can however create a 
subclass of a class to which you are not allowed access.

If you want to test the access mechanism, then follow this 
example.

1.  Create three user groups (for example, Developers, 
Contractors and Guests).  Set the levels for the groups to 
900, 600 and 500 respectively.

2.  Add three users, one in each group.

	user	user group
	----	----------

	Bill	Developers
	David	Contractors
	Justin	Guests

3.  Logon as David and enter the classes: Wheel and Engine.
4.  Logon as Justin and enter the classes: Body and Door.
5.  Logon as Bill and enter the classes: Vehicle, Car and 
Truck, where Vehicle is the superclass of both Car and 
Truck.
6.  Now logon as each user again and you will see which 
objects they are allowed access to.


Code Generator Options
======================

There is an option for the code generator that determines the level 
of detail for comments in the generated code.  We suggest you set 
it off for a start.  This will simplify the look of the code you 
generate while testing, which will make it easier to see what the 
code generator does.


To Logout
=========

When you select logout from the File menu, it is a two step 
operation.  The login screen is displayed first, giving the 
choice to enter again as another user, or to logout.

If you want to exit directly in one step, press Alt + F4.


New features not described in the manual
========================================

Quickhelp: Use <alt>+F1 or the Help/Quickhelp menu item to toggle the
	   Quickhelp.

F5: 	this key doesn`t call the quick reference window anymore, but 
	displays the Query window (call the quickref with Shift+F5). 
	You can use the Query window to quickly acces objectbase elements. 
	As windows always appear behind dialogs, the query window might be 
	obscured. 

	In the Query window
	-	select the scope of the search,
		("Definitions" searches all preprocessor definitions) 
	-	enter a search string,
		(you can use "*" as a wildcard at the end of the string). 
	-	click the Display Result button. OEW displays all matches on 
		the left-hand side of the window. 
	-	Select one of these results. OEW displays the source code 
		that will be generated for this element (you can select this
		text and copy it to the clipboard).
	-	Alternatively, you can double-click one of the search 
		results to edit this objectbase element.


F11: 	in an editor entry field or an editor window opened with an Editor 
	button, this key opens the dialog of the objectbase element under
	the cursor. If there are multiple elements of this name (e.g. a
	class and its constructor), you can select which you want to edit.


Non-modal dialogs: many of OEW`s dialogs can be left open while editing 
	another element.  


Parser: OEW can recognize #include blockers:
	-	in header files:
		#ifndef INCLUDE_BLOCKER
		#define INCLUDE_BLOCKER
		<header file>
		#endif
		OEW enters these #include blockers into the module
		definition.

	-	in include statements
		#ifndef INCLUDE_BLOCKER
		#include include_filename
		#endif

		if there is no module in the objectbase with the filename 
		include_filename and the #include blocker INCLUDE_BLOCKER,
		OEW cannot recognize the statements. You either have to
		activate "Import all" or "Execute #includes" in the import 
		dialog, or pre-define modules with the appropriate #include 
		blockers before parsing. 

		When parsing, OEW does not enter the #include blockers into 
		a module as it generates them automatically.


Known manual errata
===================

You cannot paste global datatypes and classes from the clipboard into a 
class.



The Great Unsolved Problem (GUP) example
========================================

The purpose of this example is to show a more complex example.

The problem
-----------

Imagine a transportation agency with a given number of trucks. Every day 
a number of packages have to be delivered to customers in different cities. 
Each truck can transport several packages depending on their combined volume
and the loading order. The aim is to solve the two problems of the "best 
3-dimensional packing" and the "best routing" of the trucks simultaneously 
- using the possibility of exchanging packets among the trucks. The 
algorithms are based on both the travelling salesmen algorithms and 
genetic algorithms.

GUP was developed by students at Frankfurt University in Germany. From 
the beginning of the project OEW and Borlands C++ compiler have been 
used. We would like to thank Professor Wolfgang Koenig and his team for 
allowing us to use the GUP example as a more complex example of an 
OEW objectbase.


The GUP user interface
----------------------

GUP covers many different algorithms and settings. To run the example, 
try the following combination of parameters:


1.	Open the GUP.OEW objectbase.
2.	Select "Execute" from the "Make menu".
3.	Choose the menu item "Population New".
4.	Insert the number of packages (for example: 100) in the "Cities" 
	field and check the "Best Route" and the "Best Packing" boxes 
	in the "World" dialog.
5.	Enter the number of trucks (for example: 4) and leave the other 
	options unchanged in the "Population" dialog.
6.	Check the "2-Opt" box and leave the other options unchanged 
	in the "Parameter" dialog.
7.	Select the menu item "Window Arrange".
8.	Run the example by choosing the menu item "Population Start".
9.	Terminate GUP by choosing the menu item "Population Stop", and 
	closing the main window.

Please note that it may take a while for menus to drop down when the 
application is running.  Let the application run for a while and you 
will see that the routes and packing arrangement for each of the four 
trucks are updated.  Also the data in the top window is updated, in 
particular the "Best" and "Mean" information in the third line. Watch the 
decreasing "Best" to see how the optimization works.

