Introduction

In this documentation we will explain you how to use EiffelVision in you Projects:

• Introduction
• Technical Information
• Getting Started
• How to configure your Ace file
• Some working examples

The EiffelVision library provides a solution to one of the central needs of software developers: a high-level approach to graphical development. In particular, EiffelVision is one of the few products that support both "GUI" programming (managing windows, panels, buttons and other user interface objects) and graphical manipulations (geometric figures - circles, polygons and the like, including complex figures of an arbitrary level of nesting).

EiffelVision is a key element of our technology; all of our current products (e.g. EiffelBench, EiffelBuild, EiffelCase, ArchiText) use it, and most of our customers' applications also rely on it. We are putting considerable effort into building the next generation of EiffelVision so that it will continue to support the needs of our customers.

Portability is a key concern in EiffelVision. Even though the product evolved in part from a Motif library, it also supports Windows programming.

Even though we hear frequent siren calls - including on comp.lang.eiffel - of the form "Forget about portability, all we need is a good [fill in some API here, usually Windows] encapsulation", we think it is our duty to Eiffel users, and one of the major attractions of a such a library, to provide a platform-independent solution, even if not all users are concerned about portability yet.

In fact, the relationship between portability and adaptation to specific platforms is not necessarily "either-or". This realization explains the current direction of evolution for EiffelVision.

Taking a critical look at EiffelVision, one may make two comments that at first sight appear contradictory:

• For some, EiffelVision is too abstract: they feel that it is not close enough to, say, the Windows API.
  
  
• For others, EiffelVision is not abstract enough: the library's view of how its users should do things is still influenced by its Motif origins.
  

Both of these criticisms are to a certain extent justified; but one can answer them without contradiction. It is possible to make EiffelVision:

• 1. More abstract, by removing anything that is Motif-specific or just Motifish.
  
  
• 2. More concrete, by building platform-specific layers for each of the important APIs: Windows, X/Motif etc.
  

This is the basis of the new EiffelVision architecture.

Technical Information

Task 1 is the natural evolution of EiffelVision. Cleaned up from some Motif specificities, made more general and more powerful, EiffelVision will be even more simple and intuitive to use, allowing a beginner to put together a graphical application very quickly. The result, of course, will be fully portable.

Task 2 has led to the design of a new library: WEL (the Windows Eiffel Library). WEL is an encapsulation of the Windows graphical API, meant for those developers who are focusing on Windows and want to have access to the entire set of mechanisms of that platform.

Similarly, the Motif-specific part is now encapsulated in a new library: MEL (the Motif Eiffel Library).

EiffelVision, WEL, MEL and similar libraries are not separate developments: the platform-specific parts of New EiffelVision are entirely programmed on top of WEL in the Windows implementation and MEL in the Unix and VMS implementations. So WEL and MEL are not separate developments: they are the platform-specific parts of EiffelVision. The following picture represents the new architecture:

For a user, the rationale for using either library level is clear:

• The platform-specific level (WEL, MEL, ...) provides access to all of Windows and most of Motif, at the expense of portability.
  
  
• The EiffelVision level guarantees portability, but not all platform-specific facilities will be available (although it is likely that any really useful facility which is not present in EiffelVision at a certain stage will find its way into it at a later release, implemented through the native mechanisms on some platforms and emulated elsewhere).

It is also possible to mix both level, for example to take advantage of platform-specific GUI facilities on some platforms while keeping most of the software portable.

This approach provides a comprehensive solution to user needs.

Perhaps the most interesting aspect of WEL is that it does more than just cover the needs of some Eiffel developers for a direct interface to Windows graphical mechanisms. The other audience includes anyone interested in writing graphical applications under Windows simply, safely and effectively - whether or not such a person is already an Eiffel user. To such people, WEL provides a much nicer interface than the other techniques that we know of. This is due to the benefits of the Eiffel approach -- abstraction, inheritance, command classes, reusable components from EiffelBase etc.

Getting Started

To use EiffelVision, you need to install WEL, MEL or GTK. But these library should be installed once you have installed Eiffel Bench.

Remarks :

The following classes have been made obsolete from 
version 3.3.7:

Kernel classe:
IO_HANDLER

Oui widget classes:
LABEL_G, PUSH_BG, SEPARATOR_G, TOGGLE_BG, SCROLL_LIST
LIST_MAN, MESSAGE, PROMPT

Context data classes:
CIRCNOT_DATA, FOCSOUT_DATA, MAPREQ_DATA, SELCLR_DATA
CIRCREQ_DATA, FOCUSIN_DATA, MESSAGE_DATA, SELNOT_DATA
CLRMAP_DATA, GRAPEXP_DATA, MULTIPL_DATA, SELREQ_DATA
CONFNOT_DATA, GRAVNOT_DATA, NOEXP_DATA, TOGGLE_DATA
CONFREQ_DATA, KEYMAP_DATA, PROPERT_DATA, UNMAP_DATA
CREATE_DATA, LEAVE_DATA, REPAREN_DATA, VISIBLE_DATA
DESTROY_DATA, MAPNOT_DATA, RESIZE_DATA, ENTER_DATA 
MAPPING_DATA, SCALE_DATA

To include these obsolete classes into your application
you must follow these steps:

1. If you are using MOTIF, change the declaration of the toolkit 
initialization from MOTIF to OBSOLETE_MOTIF (for windows, change 
the declaration from MS_WINDOWS to OBSOLETE_MS_WINDOWS)
2. Include the following clusters into your Ace file:
obsolete_oui: "$EIFFEL5/library/vision/obsolete/oui";
obsolete_toolkit:"$EIFFEL5/library/vision/obsolete/toolkit";
obsolete_motif: "$EIFFEL5/library/vision/obsolete/motif";

How to configure your Ace file

In order to use EiffelVision in an Eiffel Project, you have to include in your project, the right clusters and the right external files. Thus, you need to configure your Ace file.
You can get all the information about Ace files here.

However, we strongly recommend you to use the precompiled version of EiffelVision, as the compilation of this library is pretty long.

If you wish or you need to compile EiffelVision you can include all the following clusters. :

-- EiffelVision

vision: "$EIFFEL5/library/vision";
vision_kernel (vision): "$/oui/kernel";
vision_widgets (vision): "$/oui/widgets";
vision_context_data (vision): "$/oui/context_data";

vision_figures (vision): "$/figures";
vision_tools (vision): "$/tools";

-- Toolkit

vision_toolkit (vision): "$/implement/toolkit";
vision_toolkit_kernel (vision_toolkit): "$/kernel";
vision_toolkit_widgets (vision_toolkit): "$/widgets";
vision_toolkit_support (vision_toolkit): "$/support";

-- Implementation clusters for x/Motif

vision_imp (vision): "$/implement/motif";
vision_imp_kernel (vision_imp): "$/kernel";
vision_imp_widgets (vision_imp): "$/widgets";
vision_imp_support (vision_imp): "$/support";

vision_imp_x (vision): "$/implement/x";
vision_imp_x_kernel (vision_imp_x): "$/kernel";
vision_imp_x_support (vision_imp_x): "$/support";

If you want to use MEL library you can include in your Ace file :

all mel: "$EIFFEL5/library/mel/";

If you want to use WEL library, you can include in your Ace file :

all wel: "$EIFFEL5/library/wel/";

Then, you need to include some internals to use EiffelVision:

• For Windows

external

    include_path:
                    "$(EIFFEL5)\library\wel\spec\windows\include";

    object:
                     "$(EIFFEL5)\library\wel\spec\$(COMPILER)\lib\wel.lib";

• For Unix

external

    include_path:
                        "$(EIFFEL5)/library/mel/Clib";

    object:
                        "$(EIFFEL5)/library/mel/spec/$(PLATFORM)/lib/libMel.a",
                        "$(EIFFEL5)/library/mel/spec/$(PLATFORM)/lib/libXpm.a",
                        "-lXm -lXt -lX11 -lXext -lXp"

To see some Working Example of Ace file, you can check our Examples. 

Some working examples

We developed a few examples using EiffelVision that you can try to see how to use this library.

They are located in "$EIFFEL5/examples/vision"

You can especially check the example : test_all_widgets, located in "$EIFFEL5/examples/vision/test_all_widgets"