OS/2 Shareware BBS: 10 Tools/10-Tools.zip/oewoe2.zip/readme.txt

Text File | 1994-03-29 | 20KB | 551 lines

(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 Borland┤s 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 Borland┤s 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.