Copyright: ® PowerBasic, Inc.


Help Contents
Contents

Presenting the Power Basic Development Kit for MS Windows

Overview

General principles

Structure of a PBDK application

A simplified Event Mode

What is a Session ?

The DV Windows

Dialog Boxes

Controls: Buttons, Scroll Bars, Edit Boxes ...

Menus, Popup Menus

Drawing and Painting in a Window

Printing

Windows Interface Editors, Resource Files

Timers

The Clipboard

Launching MS Windows and DOS Applications from DV

The DDE Protocol

Loading and Calling DLLs

How to Extend the Standard MS-Windows Controls

Preemptive Multitasking

MDI

Drag and Drop

Self Resizable Controls

Virtual Screens

Metafiles

Owner Draw Combo and List Boxes

The Dolce Vita Custom Controls

Getting Started

Introduction

Setting up Dolce Vita

Creating your first DV application: Hello World!

Creating a Dialog Box and an Event Loop

More Controls

Opening a Dialog Box from a Resource File

Menus

Menus and Resource Files

Windows and Graphics

Printing

Conclusion


Overview

This document is a quick survey of the different functionalities provided by the PowerBasic Development Kit 1.5 for MS Windows. (PBDK). All of the aspects of the PBDKintroduced here are detailed in the product documentation. The PBDK relies on the Dolce Vita 1.5 technology developed by SummerSoft.


General principles

A Client Server architecture

The PBDK is fully compatible with PowerBasic

A Multitasking Server


A Client Server architecture

The Dolce Vita technology, on which the PBDK relies, proposes a new way of accessing the MS Windows API. Instead of encapsulating the MS Windows objects in a dedicated language, or in a set of classes for C++, DV uses a Client Server architecture. In so doing it provides a set of language interfaces: Basic,  Pascal, C, and Clipper; for different environments: DOS, DOS Extenders, and MS Windows itself. Dolce Vita provides all the connected languages with the same simplified access to the Windows resources: Windows, Dialog Boxes, Drawing functions, the Clipboard, the DDE protocol, DLLs, and so on. Dolce Vita is much more than a software bridge between the DOS tools for example, and MS Windows: it does much of the low level work to maintain the windows for which it responds, or the DDE links.


The PBDK is fully compatible with PowerBasic

The PBDK is fully compatible with the PowerBasic IDE, third party libraries and debugger.

The PBDK is just another third party library for PowerBasic. It appears to the PB developper as a library offering a 350 functions API. As described in the paragraphs below, a PB application can start making use of Windows resources with as less as 5 PBDK functions. Furthermore, the PB developpers can make use progressivly of the Windows functionalities through DV, without having to rewrite its existing code for that purpose.


A Multitasking Server

Dolce Vita, as a Server,.is a MS Windows application provided with the capability to communicate with, DOS applications. Dolce Vita is able to serve several of those applications at the same time. Windows 3.x running in Enhanced Mode is able to open several DOS Boxes  and run them in Preemptive Multitasking, meaning that each DOS Box receives, in turn, a Time Slice during which it runs. Each DOS boxes is able to run a different Dolce Vita application at the same time.


Structure of a PBDK application

The minimum structure of a PBDK application is very simple. A PBDK application must connect itself to DV before attempting to call any of the DV functions, and it must disconnect before the end of the Session. DV provides two functions for that purpose, one for the connection, and one for the disconnection. As soon as connected, an application is able to use any of the MS Windows resources through the PBDK API. The paragraph below provide simple samples to demonstrate the generic structure of DV applications.


A simplified Event Mode

MS Windows is a message-based system. Basically a MS Windows application is a loop where the sent messages are read and processed. MS Windows sends a lot of messages to its applications to make them repaint their windows when they are moved or resized for example. Dolce Vita does most of this low level work for its applications. The DV windows management is very simple for example. A DV application only has to create a window and it is then able to perform any painting or drawing operations, it can create Controls such as Push Buttons or List Boxes without ever having to deal with the low level messages sent by MS Windows.

Dolce Vita associates an individual message queue with each of its connected applications (clients). It records in those queues all of the messages resulting from user input: mouse, keyboard and Control interaction . When the user clicks on a Push Button for example, DV sends to the application owning this Control a notification message to let it know what is happening. A DV application is then able to receive all the user input and to process it. DV receives, filters, and processes the low level messages. A DV application can therefore create Event Loops, from within which all the received messages are processed.


What is a Session ?

A Session is a top level Window that can be described as the Working Area of a DV application, where it will open Windows, or set a Menu. Each DV application has its own separate Session Window. This Session can be moved, resized, iconized or maximized by the user and DV does all of the corresponding work for the owning application. Likewise, a Session provides horizontal and vertical Scroll Bars with which the user can scroll the Windows installed in the Session, this is again done automatically by DV for its applications.


The DV Windows

Dolce Vita makes the creation and use of a Window very simple. A DV application only has to create it and chose its Style (whether this Window has a Caption Bar, Scroll Bars, a Resizable Frame and so on). DV handles all the low level work to repaint it, move it, minimize or restore it. An application can also create, modify move or destroy any kind of Controls (Push Buttons, Check Boxes, Combos ...) in any of its Windows. A Window is confined in the Session of its application.


Dialog Boxes

DV provides a second type of windows: the Dialog Boxes. These objects have a very similar behavior to DV Windows, but a DV application cannot draw or paint them, and they are not confined in a Session. Dialog Boxes are floating windows, which can appear anywhere on the screen. A DV application can open Dialog Boxes and then create Controls. It will receive messages from a Control installed in a Dialog Box in the same way as those from Controls installed in Windows. A Dialog Box can be made Modal, restricting the user from clicking anywhere else on the screen, on other Windows or Menus. In this way an application can force the user to complete a specific action.


Controls: Buttons, Scroll Bars, Edit Boxes ...

A Control is a predefined object that carries out a specific kind of input or output. To get a name from the user, you can put an Edit Box in a Window or in a Dialog Box, for example. This Control will receive all the characters pressed by the user and display them without any implication of the owning DV application. A Button Control repaints itself when the user clicks on it and sends a message to its owning application. In short, a Control is an object providing a standard behavior (for receiving the user input and relaying messages to its owner application).

The different MS Windows Controls are:

Buttons:

Push Buttons
Check Boxes
Radio Buttons

Edit Boxes

List Boxes

Combo Boxes

Scroll Bars

Statics

DV provides a set of functions for each of these different types of Controls which allow applications to open and use them in their Windows, or Dialog Boxes. Each type of Control sends messages in response to user interaction. Since DV applications receive these messages in their individual message list they can therefore deal with all the user requests upon them.


Menus, Popup Menus

Most of MS Windows applications use Menus so as to let the user choose commands or options. Dolce Vita provides full access to these Menus. A Menu is a set of Items representing the commands of an application. An Item can be displayed using either text or a bitmap. The user tells the application to perform a command by selecting a Menu Item using the mouse or the keyboard. When an Item is chosen, the application is sent a message giving information about its activation. DV provides a set of functions to let an application build and manage any kind of Menu or Sub Menu, and receive the messages resulting from the user's actions.


Drawing and Painting in a Window

A DV application is able to perform very simply any drawing or painting operation in its windows. It can use Pens and Brushes to paint or draw lines, rectangles, ellipses and polygons as well as pies or charts. It is also very easy to load a Bitmap (BMP) file and to paint it anywhere, in any size, in a Window. The True Type Fonts are also available to DV applications.


Presenting the Power Basic Development Kit for MS Windows - Printing
Printing

With DV, printing text with True Type fonts, lines circles or bitmaps is as easy as painting them in a Window. In fact the code is exactly the same in both cases. All the graphic functions that can be used in a Window can be used with the printer. Additional functions to control the printer (starting a new page for example) are also available.


Windows Interface Editors, Resource Files

All the items implied in a User Interface (Dialog Boxes, Menus, Icons, Bitmaps ...) can be defined without any programming, thanks to the MS Windows Interface Editors. These items, known by their name, are stored in standard Windows Resource Files. DV provides a set of functions to load these files and extract any item out of them. Therefore a PBDK developer can launch the WhiteWater Resource Kit, for example, to create interactively his Dialog Boxes, Menus, Icons and Bitmaps and use them directly in his programs.


Timers

A Timer is a MS Windows object sending specific messages at any specified period. DV lets its applications create such objects, and it records the corresponding messages in their list.


The Clipboard

The Clipboard is one of the data exchange features of MS Windows. It is a common area where Windows applications can store data of different formats. DV makes it very easy to copy data from or to the Clipboard in any format supported by MS Windows.


Launching MS Windows and DOS Applications from DV

A DV application has the ability to launch any MS Windows application and later close it. This can also be done for DOS applications, which then run in separate DOS boxes.


The DDE Protocol

DDE is a protocol for data exchange between MS Windows programs. It provides the low level mechanism to establish a conversation between a Client and a Server and then let them exchange commands and data. This protocol is based on a set of MS Windows messages. DV proposes an encapsulation that makes it very easy to master. A DV application can therefore act as a DDE Client. It can connect to Excel for example, and send it commands or request specific data. A DV application can also be recorded by Windows, through DV, as a DDE Server and deal with commands sent by standard DDE Clients.


Loading and Calling DLLs

A Dynamic Link Library (DLL) is a MS Windows module providing a set of functions to be loaded and unloaded at any time by a MS Windows application. When a DLL is loaded, it can be used by any of the MS Windows application running at this moment. This very powerful feature is available to the DV applications: even while running in a DOS box, they can load any MS Windows DLL and call its functions !


How to Extend the Standard MS-Windows Controls

The standard set of Controls (Buttons, Edit Boxes, List Boxes ...) can be extended in two different ways. First, a Windows application is able to create a special type of Buttons: the Owner Draw Buttons. It chooses the aspect of such buttons in all their different states: up, pressed, with the focus ... Secondly, MS-Windows also defines a special format of DLL: the Custom Control DLLs. Such modules provide the code to manage new Controls: they control their aspect and deal with the user interaction exactly the same way as Windows does for its own Controls. Both of these mechanisms are available to DV programs, which are able to load Custom Control DLLs, and then create Controls out of them. Many Custom Control DLLs are available from third party vendors. Such Custom Controls can, for example, provide the ability to check the format of user's input in an Edit Box.


Preemptive Multitasking

Dolce Vita is a Multitasking Server, in that it is able to serve several applications at the same time, each of them running in a separate DOS box. Windows in 386 Enhanced Mode provides Preemptive Multitasking to these DOS boxes: they are given in turn a limited amount of time (a Time Slice). When the time slice of a DOS box is over, Windows halts it and runs another task, which is why this multitasking is said preemptive. Since all the DOS boxes have the same simultaneous access to Windows through DV it is advantageous to build MS Windows preemptive multitasking applications with the PBDK. DV provides a set of functions to make these DOS boxes exchange data, thanks to a named Common Zone, and synchronize with Semaphores. The DV applications can also send messages to each other.


MDI

Multiple Document Interface (MDI) provides applications with a standard interface for displaying multiple documents.

The PBDK 1.5 proposes a complete and simple MDI support in the form of a plug-in DLL (DVMDI.DLL) to be used through a special and small API.

Dolce Vita offers extended mechanisms which make it possible to design a complete MDI framework, including toolbars and status bars, using the Borland Workshop and open it with one function call. MDI child windows can also be designed with a Resource Editor, and create it in a PBDK application with one single function call.


Drag and Drop

The PBDK fully supports the MS Windows 3.1 Drag and Drop. With an application implementing the drag-drop feature, a user can select one or more files in the File Manager, drag them to a window of this application, and drop them there. The application in which the files were dropped receives a message, which it can use to retrieve the dropped filenames and the coordinates of the point where they were dropped.


Self Resizable Controls

The PBDK applications can assign a Resize Style to their Controls (edit boxes, list boxes ...), to make them resize by the DV engine when their parent window or dialog box is maximized or resized. This feature makes it very easy to create complex toolbars or status bars in a MDI Frame for example.


Virtual Screens

Dolce Vita 1.5 proposes a new type of graphic objects, named Virtual Screens, where a PBDK application can perform exactly the same graphic operations as in a Window or to the Printer. These Virtual Screens can then be inserted into Owner Draw Combos, List Boxes or Graphic Buttons, or linked to Graphic Controls. A Virtual Screen can be used at the same time with several Combos, Owner Draw Buttons, Graphic Controls ...


Metafiles

The PBDK fully supports Metafiles. A Metafile is a collection of graphic commands that produces images. A Metafile is created by a special function returning a handle which can be used with all the graphic functions. A Metafile can be used to fill Owner Draw Buttons, Combo and List Boxes. It can also be linked to a Graphic Control. A Metafile can be copied to or loaded from a file. DV 1.5 supports both placable and non placable metafiles.


Owner Draw Combo and List Boxes

Standard Combo and List Boxes contain text. Window offers the possibility of creating Combo and List Boxes containing graphic objects instead. Implementing those Owner Draw Combo and List Boxes using the Windows SDK is difficult and tedious.

Dolce Vita 1.5 makes these powerful Controls easy, in conjunction with Virtual Screens and MetaFiles. A PBDK application only has to prepare a collection of Virtual Screens, paint them the way it wants, using any complex or simple graphic operation (with pens, brushes, True Type fonts, metafiles ...) and then insert them in one or several Graphic Combo box or List box.


Presenting the Power Basic Development Kit for MS Windows - The Dolce Vita Custom Controls
The Dolce Vita Custom Controls

What is a Custom Control DLL

The Dolce Vita Custom Controls


What is a Custom Control DLL

Custom Control DLLs are a special kind of DLL which implement new types of Controls extending the predefined set of Windows Controls.

A Custom Control DLL can be loaded by any Interface Editor. New icons corresponding to the DLL's Controls will then be inserted in the Interface Editor ToolBar. The new Controls are created the same way as standard Controls: go to the Toolbar, click on the icon corresponding to the chosen Control and insert it in the Dialog Box you are currently editing. Double click on this Control to edit its properties, a Style Dialog Box will be displayed for that purpose.


Presenting the Power Basic Development Kit for MS Windows - The Dolce Vita Custom Controls - The Dolce Vita Custom Controls
The Dolce Vita Custom Controls

Dolce Vita 1.5 provides two Custom Control DLLs which will let you include very easily Graphic Controls embedding pictures (metafiles, bitmaps) or Owner Draw Buttons in your Dialog Boxes. The DV Graphic Controls can be assigned a Resize Style, they can be tested from within the standard Resource Editors. You can use Bitmaps, Metafiles or Icons to define your Owner Draw Buttons.


Introduction

This chapter will guide you in your first steps with the PBDK. Most of the principles you will have to master to create real Windows applications with the PBDK are demonstrated in the following set of short programs.

The first sample will show you how to create a first PBDK executable file, which will simply open a Message Box.

Next you will create a real Dialog Box and open an Event Loop to deal with the messages it sends. You will see how simply it can be done using the Windows Resource Files.

The third sample will show you how to create and use Menus.

The following example will let you create Windows in which you will paint a Bitmap loaded from a BMP file, and display text using a True Type Font.

The last example of this chapter will show you how to use the Printer and how to print a Bitmap file.

A good understanding of these short programs will make Dolce Vita very easy to learn and use.

The PBDK offers features not described in this section: MDI, Drag and Drop, Virtual Screens. See the product documentation for more information.


Setting up Dolce Vita

Make sure you have installed Dolce Vita properly on your PC. To work with DV you will need a windowed DOS Box, where you will edit, debug and run your applications (see Figure 1.1). Launch Windows and then DVSERVER (click the DV Icon in the DV Group). You can also move the DVServer Icon to the Startup Group. It will then be automatically launched with Windows. DV provides a way to simultaneously launch the DV Server and a DV application, see the User Manual Appendix 1: Installing a DV Application for more information.


Creating your first DV application: Hello World!

Creating a DV executable file

Launching a DV application

Structure of a DV Application


Creating a DV executable file

The PBDK is just another PowerBasic add on library. All you have to do to use the DV functions is then to link the provided library to your programs.

The basic steps involved in the creation of a DV executable file are:

Copy the DVMODEL.PB3 source code to your own empty source file, HELLO.PB3 for example.

Compile this HELLO module and link it with the DV library.

You now have a HELLO.EXE file that can be launched under Windows.


Launching a DV application

To launch HELLO, your first DV application, go to the prompt in your windowed DOS box, in Windows, and type HELLO. You can also do this from your Integrated Developement Environment (IDE) in this box. Note that all the debugging capabilities of the PB3 IDE are still available with Dolce Vita (See Figure 1.1).


Structure of a DV Application

Each language connected to Dolce Vita is provided with a DVMODEL source code file to be copied to any new DV application. The model contains the structure of a DV application:

Figure 1.1: Creating a DV application from the PB3 IDE.

Example1.1: DV model

This application does not do anything, it is just a skeleton. Let's add just a few lines of code to make it a real Hello World ! Windows application.

' Declaration of the DV functions and constants
$INCLUDE "PB3DV.PB3"

' connection to DV
CALL InitExecution("DVMODEL",RESETAPP%)
CALL ReadErrorNumber(DVError%)
IF DVError% > 0 THEN END

' disconnection, end of the program
CALL EndExecution

Example 1.2: Hello World !

' Declaration of the DV functions and constants
$INCLUDE "PB3DV.PB3"

CALL InitExecution("HELLO",RESETAPP%)
CALL ReadErrorNumber(DVError%)
IF DVError% > 0 THEN END

CALL MessageBox(0,"Hello World!",
"Welcome to Dolce Vita",
MBICONINFORMATION%,
code%)

CALL EndExecution

Here is your first DV application !

Note: Manifest Constants

Manifest constants such as MAXNAME or MBICONEXCLAMATION are part of the DV interface.


Creating a Dialog Box and an Event Loop

This short program shows several of the most important principles you will have to know to master Dolce Vita:

How to create Dialog Boxes and Controls.

How to receive the user's input on these objects.

How to process this input.

How to modify and manage Controls.

Here is the code of this program, we will discuss about it later. (See Figure 1.1)

Example 1.3: Creating a Dialog Box

' Declaration of the DV functions and constants
$INCLUDE "PB3DV.PB3"

' IDs of the Buttons and Edit Box created and used in this
' program
IDEDIT%=100
IDOK%=1000
IDCANCEL% =2000

' Connection to DV Server
AppName$="DVMODEL"
CALL InitExecution(AppName$,RESETAPP%)

' Creating an empty Dialog Box
' The Title string will appear in the Caption Bar
Title$="Title of the Dialog Box"

' Style tells what Attributes are to be given to the Dialog Box:
' Caption Bar, System Menu, Scroll Bars. Note that the
' WS_CAPTION, WS_SYSMENU constants are provided by the
'Interface.

Style&=WSCAPTION& OR WSSYSMENU& OR
WSMINIMIZEBOX&

' (Left,Top) is the position of the Upper Left Corner of the Dialog
' Box in the screen, in pixels. Width is its horizontal dimension,
' Height its vertical dimension.

vLeft%=32
vTop%=32
vWidth%=200
vHeight%=72
CALL CreateDlg(Style&,Title$,vLeft%,vTop%,vWidth%,vHeight%,
hDlg%)
'
' A Dialog Box is identified by a Handle, hDlg, returned by
' CreateDlg.
'
'
' At this moment, the new Dialog Box has been displayed with its
' attributes (Caption Bar, System Menu and MinimizeBox) in the
' screen. It does not contain any Control.
'

' Adding an Edit Box in the Dialog Box
'
' An EditBox is created in a DialogBox. The first parameter
' required by the CreateEdit function is the Handle of this
' DialogBox: hDlg.
'
'An Edit Box creation requires very similar parameters compared 'to a Dialog Box creation:
'
' Style: specifies the attributes to be given to the new Edit Box.
' (Left,Top,Width,Height): position of the Control in the Dialog
' Box.
'
' CreateEdit requires an additional parameter, ID, which identifies
' the new Control in its parent Dialog Box. This parameter will be
'very useful when the program will have to treat the user input on
' the Dialog Box.
'
' The CreateEdit function also returns the Handle, hEdit, of the
' new Edit Box.
'

Style&=ESAUTOHSCROLL& OR ESBORDER&
vLeft%=8
vTop%=8
vWidth%=184
vHeight%=24
CALL CreateEdit(hDlg%,IDEDIT%,Style&,
vLeft%,vTop%,vWidth%,vHeight%,
hEdit%)

' Adding two Buttons in the Dialog Box
'
' A Button creation requires the same set of parameters as an
' Edit Box creation:
'
'	Handle of the Dialog Box where to open it (hDlg).
'	ID of the Button.
'	Style.
'	Position of the Button in the Dialog Box.
'	(Left,Top,Width,Height)
'
' CreateButton returns as well the Handle of the new Button.
'
' CreateButton requires one additional parameter: its Title, text to
' be displayed in the new Button.
'
Title$="&OK'"
CALL CreateButton(hDlg%,IDOK%,BSDEFPUSHBUTTON&,
8,40,92,24,Title$,hOK%)
Title$="&Cancel'"
CALL CreateButton(hDlg%,IDCANCEL%,BSPUSHBUTTON&,
100,40,92,24,Title$,hCancel%)

'
' Buttons and Edit Boxes are Controls. Most of the user's
' interaction on them is managed by Windows. Each Control is
' identified by a Handle. hOK and hCancel for the Buttons. hEdit
' for the Edit Box.
'

' How to receive the user's input on a Dialog Box and its
' Controls.

'
' Creating an Event Loop to receive the user's input on the Dialog
' Box. Each time the user clicks one of the Buttons or strikes a
' key, a message is sent and it can be read with the GetMessage
' function.

DIM XParam%(4)
Cmd$=SPACE$(64)

OK%=1
WHILE (OK=TRUE) DO
' Reading the next message sent by the Dialog Box.
CALL GetMessage(hWnd%,Msg%,wP%,Xc%,Yc%,
XParam%(1),Cmd$)
'
' GetMessage returns all the information about the latest
' message:
'	hWnd is the Handle of the sending object. (Dialog Box,
'	Window, Timer, DDE Link ...)
'	Msg is the message number, it tells what is happening
'	exactly.
'	wP is the main parameter of the message. Its meaning
'	depends on Msg, the message number.
'	(Xc,Yc) is the position of the Cursor in the hWnd
'	Window.
'	XParam is an array of parameters giving additional
'	information about the message.
'	Command is a string describing the received message.
'
'
' Each time the user clicks on a Button, or in the Edit Box, a
' Msg%=WMCOMMAND% message is sent. wP contains the ID
 ' of the Button or of the clicked Edit Box.
'
IF Msg%=WMCOMMAND% THEN
'
' The Message Loop ends when the user clicks on one of
' the Buttons.
'

' The user has clicked on the OK Button *)
IF wP%=IDOK% THEN OK%=0

' The user has clicked on the Cancel Button *)
IF wP%=IDCANCEL% THEN OK%=0
END IF

WEND

'
' When the user has clicked on one of the Buttons, OK or Cancel, ' the program reads the Edit Box contents and displays it in a ' Message Box.
'

' Reading the contents of the EditBox
Size%=MAXSTR%
Text$=SPACE$(Size%)
GetCTLText(hEdit%,Text$,Size%)

' Displaying the contents of the Edit Box in a Message Box
Title$="Contents of the Edit Box"
CALL MessageBox(0,Text$,Title$,
MBOK% OR MBICONEXCLAMATION%,
Code%)

CALL EndExecution

Figure 1.2: A first Dialog Box

General structure of a PBDK application.

This sample follows the basic structure of most of PBDK applications:

Open a first set of objects (Dialog Boxes, Menus, Windows.)

Create an Event Loop where to receive and treat the user's input (clicks, keystrokes etc.), and modify the existing objects or create new one.

Creating DV objects.

This sample manipulates somewhat different objects: a Dialog Box and Controls (Buttons, Edit Boxes). These objects are in fact very similar:

The functions used to create them require similar parameters:

The position of their Upper Left Corner. (Left,Top)
Their size (Width, Height).
A Style.

They are all identified by a Handle (hDlg, hOK, hCancel, hEdit).

Controls require at least two additional parameters:

The Handle of the parent Dialog Box where they are to be created (hDlg). The (Left,Top,Width,Height) parameters give the position of the Control in the Client Area of the parent Dialog Box.

An ID, which identifies a Control in its parent Dialog Box. This ID is one of the parameters given with a message sent by a Control when the user interacts with it (click on a Button, for example). Using this ID makes it easy for a program to know where a message comes exactly from.

Some Controls, such as Buttons, require a Title, which is text to be displayed in association with the Control.

Event Loops

The Event Loop created in this sample is also generic. After having created objects, here a single Dialog Box, an application must wait for the user input and treat it. Here the only taken action is to end the event loop when the user clicks one of the buttons.

An event loop looks like this:

WHILE OK%=1

CALL GetMessage(hWnd%,Msg%,wParam%,Xc%,Yc%,XParam%(1),Cmd$)
'
'The most often used parameters of a message are:
''	hWnd is the handle of the emitting message.
''	Msg is the message number, it tells what is happening
''	exactly.
''	wParam is the main parameter of the received message. Its
''	meaning depends on Msg.
'

' Dealing with messages sent by a HandleObject1 object
IF hWnd%=HandleObject1% THEN

IF Msg%=WMCOMMAND% THEN
'
' This message is sent when the user interacts
' with a Control.
'

' The IDCONTROL1 Control has been activated
IF wParam%==IDCONTROL1% THEN

...
END IF

 The IDCONTROL2 Control has been activated
IF wParam%==IDCONTROL2% THEN

..
END IF

END;

IF Msg%=WMTIMER% THEN

...
END IF
...
END IF

WEND

Managing Controls.

MS Windows provides a set of predefined objects called Controls: Buttons, Check Boxes, Edit Boxes, Combos etc... Most of the user interaction on these objects is received and treated by Windows itself. You may have noticed while playing with the previous Dialog Box that it lets you type text in the Edit Box. The Event Loop does not provide any code to control the editing of the text since this is already done by Windows.

Dolce Vita provides a set of general functions applicable to all the different types of Controls (reading- modifying the position of a Control, its text, destroying it, etc.).

Besides this, each of these Controls comes with a particular set of functions (filling a ListBox, changing the range of a ScrollBar, checking a Check Box etc.). Each of these Control types can be studied independently.

Conclusion

This sample introduces the basics of DV programming. The following examples rely on the same structure.


More Controls

This example introduces another type of Control: the ListBoxes. It creates an Event Loop where the user interaction is received and treated (See Figure 1.3).

Figure 1.3: More Controls

Example 1.4: Creating a Dialog Box with a List Box.

IDEDIT%=100
IDOK%=1000
IDCANCEL%=2000
IDLISTBOX%=3000

' connection to DV
CALL InitExecution("DVMODEL",RESETAPP%)
CALL ReadErrorNumber(DVError%)
IF DVError% > 0 THEN END

Title$="Title of the Dialog Box"
Style&=WSCAPTION& OR WSSYSMENU& OR WSMINIMIZEBOX&
Left%=32
Top%=32
DVWidth%=320
Height%=200
CALL CreateDlg(Style&,Title$,Left%,Top%,DVWidth%,Height%,hDlg%)

Style&=ESAUTOHSCROLL& OR ESBORDER&
Left%=8
Top%=8
DVWidth%=224
Height%=24
CALL CreateEdit(hDlg%,IDEDIT%,Style&,Left%,Top%,DVWidth%,Height%,hEdit%)

Title$="&OK"
CALL CreateButton(hDlg%,IDOK%,BSDEFPUSHBUTTON&,240,8,64,24,Title$,
hOK%)

Title$="&Cancel"
CALL CreateButton(hDlg%,IDCANCEL%,BSPUSHBUTTON&,240,32,64,24,
Title$,hCancel%)

CALL CreateListBox(hDlg%,IDLISTBOX%,LBSVSCROLL& OR LBSBORDER&,
8,40,224,152,hListBox%)
Path$="*.*"
CALL AddDirListBox(hListBox%,Path$,LBRW%)

DIM XParam%(4)
Cmd$="                  "

DO
CALL GetMessage(hW%,Msg%,wParam%,Xc%,Yc%,XParam%(1),Cmd$)
IF Msg% <> 0 THEN
? "Message : hWnd ";hWnd%;" Msg ";Msg%;" wParam ";wParam%;" Cursor 	";Xc%;Yc%

IF (Msg%=WMCOMMAND%) THEN
IF (wParam%=IDOK%) THEN GOTO EXT
IF (wParam%=IDCANCEL%) THEN GOTO EXT
END IF
ELSE
CALL ReleaseTimeSlice
END IF

LOOP UNTIL FALSE

EXT:

Text$=SPACE$(MAXSTR%)
Size%=MAXSTR%
CALL GetCTLText(hEdit%,Text$,Size%)

Title$="Contents of the Edit Box"
CALL MessageBox(0,Text$,Title$,
MBOK% OR MBICONEXCLAMATION%,Code%)

' disconnection, end of the program
CALL EndExecution

The structure of this example is exactly the same as the previous one:

Creation of the initial objects: a Dialog Box with two Buttons, an Edit Box, and a List Box filled with the contents of the current directory.

Opening an Event Loop to receive the user's input and take the corresponding actions.

A new type of Control has been introduced in this sample: List Box. The function which creates it (CreateListBox) is very similar to those used to create the Control types we have already used (CreateButton, CreateEdit). It requires:

The Handle of its parent Dialog Box.
An ID, used in the Event Loop
A Style.
A Position and Size in its parent Dialog Box.

CreateListBox returns a Handle as well.

A few functions specific to the List Boxes have been used:

AddDirListBox, to fill a List Box with the contents of a given directory.
StatusListBox, to read the selected line index.
GetTextListBox, to read the contents of a given line in a ListBox.

Dolce Vita provides a much more flexible and easy way of creating Dialog Boxes, thanks to the Resource Files.


Opening a Dialog Box from a Resource File

The two previous samples had to open a Dialog Box by creating each Control separately. They had to compute their Position and Size, choose a Style, an ID and so on. Using this method to create complex Dialog Boxes could become difficult and inconvenient.

MS Windows provides a mechanism of Resource Files. A Resource File is basically a text file containing a set of Scripts, each of them describing a Resource. Several types of Resources can be embedded in a Resource File: Dialog Boxes, Menus, Accelerators, String Tables, etc. Dolce Vita supports all these different types of Resources.

These Resource Files can be created, tested and modified by Resource Editors, such as the White Water Resource Kit or the Borland Resource Toolkit. Dolce Vita is compatible with all these Interface Editors (See Figure 1.4).

Figure 1.4: Creating a Dialog Box with an Interface Editor

Saving the Dialog Box shown in Figure 1.4 into a DLG3.DLG file produces a text file containing a DLG3 Script  like this:

DLG3 DIALOG 10, 35, 135, 127
STYLE WS_CAPTION | WS_SYSMENU | DS_MODALFRAME
CAPTION "Creating a Dialog Box with an Interface Editor"
BEGIN
CONTROL "", 101, "EDIT", ES_LEFT | WS_TABSTOP, 3, 4, 81, 12
CONTROL "", 102, "LISTBOX", WS_BORDER | WS_VSCROLL | LBS_SORT, 3, 17, 81, 103
CONTROL "", 103, "SCROLLBAR", SBS_LEFTALIGN | SBS_VERT, 76, 16, 9, 105
CONTROL "&OK", 104, "BUTTON", BS_DEFPUSHBUTTON, 87, 4, 43, 14
CONTROL "&Cancel", 105, "BUTTON", BS_PUSHBUTTON, 87, 18, 43, 13
END

You will recognize in this Script the same steps you would have to follow to create a similar Dialog Box by programming:

DLG3 DIALOG 10, 35, 135, 127
STYLE WS_CAPTION | WS_SYSMENU | DS_MODALFRAME
CAPTION "Creating a Dialog with an Interface Editor"

Is similar to:

CALL CreateDlg( WSCAPTION& OR WSSYSMENU& OR DSMODALFRAME&,
"Creating a Dialog with an Interface Editor", 10, 35, 135, 127,
hDlg%)

CONTROL "", 101, "EDIT", ES_LEFT | WS_TABSTOP, 3, 4, 81, 12

Is similar to:

CALL CreateEdit(hDlg%,ESLEFT& OR WSTABSTOP&,3,4,81,12,hEdit%)

The following sample shows how to create a Dialog Box out of a Resource File.

Example 1.5: Creating a Dialog Box from a Resource File.

CALL InitExecution("DIALOG",RESETAPP%)
CALL ReadErrorNumber(DVError%)
IF DVError% > 0 THEN END

CALL LoadResources("DLG3.DLG",hRes%)

CALL OpenDlgRes(hRes%,"DLG3",hDlg%)

CALL EndExecution

No matter how complicated the Dialog Box is, all the CreateDialog, CreateEdit, CreateListBox ... lines are replaced by one line: OpenDlgRes.


Getting Started - Menus
Menus

Sessions

Menus


Sessions

Before being allowed to manipulate Menus, a DV application must create a Session. A Session can be described as the Working Place of a DV application. The DV Windows are constrained in a Session. This organization makes it possible to move, iconize and maximize at the same time all the Windows required by a DV application.

Remenber that Dolce Vita is able to serve several applications at the same time, each of them opening its own Windows. Sessions make it easy to separate the Windows belonging to different DV applications.

To be displayed, a Menu has to be installed in a window, which can only be done in a Session. This is the reason why a DV application must create a Session before being allowed to use Menus.

Figure 1.5: A Session and its Menu.


Getting Started - Menus - Menus
Menus

Most of the rules applying to Dialog Boxes and Controls apply to Menus and Items also:

Menus are identified by Handles, which can be created by program, or out of a Resource File.

Menus contain Items, identified by an ID.

Menus and Items emit messages resulting from the user's interaction with them. These messages are read and treated in the same way as Dialog Box messages are.

Menus and Items come with their specific functions (add- remove an Item, enable-disable an Item ...)

The following sample shows how to create a Menu and then receive and process the messages it sends. The structure of this program will look familiar to you.

Example 1.6: Creating and using a Menu

CALL InitExecution("DIALOG",RESETAPP%)
CALL ReadErrorNumber(DVError%)
IF DVError% > 0 THEN END
'
'Creation of a Session, required to use Menus.
'
Txt$="Session"
CALL OpenSession(Txt$,32,32,600,320,hSession%)

'
' 'CreateMenu creates an empty Menu. This Menu is not displayed until it is
' installed in the current Session: cf SetMenu.
'
CALL CreateMenu(hMenu%)

'
' Adding Items in the new Menu.
' AppendMenu appends a new Item at the end of the specified Menu. This
' function requires:
''	A Flag, specifying the initial state of the new Item.
''	The ID of this Item.
''	The Text to display in this Item.
'
Flags%=0
ID%=100
Txt$="Item1"
CALL AppendMenu(hMenu%,Flags%,ID%,Txt$)

Flags%=0
ID%=200
Txt$="Item2"
CALL AppendMenu(hMenu%,Flags%,ID%,Txt$)

'
'Appending a new Item that is initially Grayed and Disabled.
'
Flags%=MFGRAYED% OR MFDISABLED%
ID%=300
Txt$="Item3"
CALL AppendMenu(hMenu%,Flags%,ID%,Txt$)

'
' Appending an Item always displayed in the right of the Menu
' (Flag=MFHELP).
'
Flags%=MFHELP%
ID%=400
Txt$="Help"
CALL AppendMenu(hMenu%,Flags%,ID%,Txt$)

'
' Setting the new Menu in the current Session. The Menu is now displayed,
' and it starts emitting messages.
'
CALL SetMenu(hMenu%)

'
' Event Loop
'
GetMsg%=1
WHILE GetMsg% <> 0

CALL GetMessage(hWndMsg%,Msg%,wP%,XCursor%,YCursor%,XParam%(1),
Command$)

'
' When no message is available, GetMessage returns a Msg=0 Message.
'
IF Msg <> 0 THEN
'
' The Msg=WMCOMMAND messages come from the Menu.
' wP contains the ID of the clicked Item.
'
IF Msg% = WMCOMMAND% THEN
PRINT " WMCOMMAND: ID of the selected Item: ";wP
END IF

'
' The Msg=WMSYSCOMMAND messages come from the System
' Menu of the current Session. wP contains the ID of the clicked
' Item. The Event Loop ends when the System Menu CLOSE Item is
' activated,
'
IF Msg = WMSYSCOMMAND THEN

IF wP = SCCLOSE THEN
'
' Opening a Message Box to ask the user if he really wants
' to end the program.
'
Txt$="Do you really want to end this Demo ?"
Caption$="MessageBox"
CALL MessageBox(0,Txt$,Caption$,
MBYESNO%,Code%)
'
' Code receives a value related to the user answer:
' IDYES, or IDNO in this case.
'
IF Code=IDYES THEN GetMsg%=0
END IF
END IF
ELSE
'
'If no message is available, the application releases its Time Slice to
'let other applications run.
'
CALL ReleaseTimeSlice
END IF

WEND

CALL EndExecution


Menus and Resource Files

As with Dialog Boxes, Menus  can be defined in Resource Files, apart from the source code. The steps involved in the creation of a Resource Menu are exactly the same as those concerning a Resource Dialog Box.

Editing a Menu with an Interface Editor produces a text file like this:

Resource File:

MENU2 MENU
BEGIN
POPUP "Popup1"
BEGIN
MENUITEM "Popup1 : Item1 ", 101
MENUITEM "Popup1 : Item2", 102
MENUITEM "Popup1 : Item3", 103
POPUP "Popup1 : Popup10"
BEGIN
MENUITEM "Popup10 : Item1", 101
MENUITEM "Popup10 : Item2", 104
MENUITEM "Popup10 : Item3", 105
POPUP "Popup10 : Popup100"
BEGIN
MENUITEM "Popup100 : Item1", 101
MENUITEM "Popup100 : Item2", 106
MENUITEM "Popup100 : Item3", 107
END
END

MENUITEM SEPARATOR
MENUITEM "Popup1 : Item4", 1
END

POPUP "Popup2"
BEGIN
MENUITEM "Popup2 : Item1", 1001
MENUITEM "Popup2 : Item2", 1002
MENUITEM SEPARATOR
MENUITEM "Popup2 : Item3", 1003
END

POPUP "Popup3"
BEGIN
MENUITEM "Popup3 : Item1", 2000
MENUITEM "Popup3 : Item2", 2001
MENUITEM "Popup3 : Item3", 2002
END

POPUP "Help", HELP
BEGIN
MENUITEM "Help : Item1", 3000
MENUITEM "Help : Item2", 3001
MENUITEM "Help : Item3", 3002
MENUITEM SEPARATOR
MENUITEM "Help : Item4", 3003
END

END

The general structure of a Menu Script named MenuName is:

MenuName MENU
BEGIN
...
END

The enclosed lines look like:

POPUP PopupName
BEGIN
...
END

or:

MENUITEM ItemName, ItemID

A Menu Script can then describe a Menu and all its Sub Menus. This structure of Menus and SubMenus is created in a single call to the OpenMenuRes function. SetMenu installs the Menu structure in the current Session and makes it immediately usable. (See Figure 1.6)

Figure 1.6: The MENU2 Menu and SubMenus.

Example 1.7: Creating a Menu from a Resource File

CALL InitExecution("DIALOG",RESETAPP%)
CALL ReadErrorNumber(DVError%)
IF DVError% > 0 THEN END
'
' Creation of a Session.
' OpenSession requires:
''	the (Left,Top,DVWidth,Height) position and size of the Session in the
''	screen.
''	the Txt text to be displayed in the Caption Bar.
' This function returns the hSession handle of the new Session.
'
Left%=32
Top%=32
DVWidth%=600
Height%=320
Txt$="Session"
CALL OpenSession(Txt$,Left%,Top%,DVWidth%,Height%,hSession%)

'
' Loading the MENU2.DLG Resource File.
'
ResName$="MENU2.DLG"
CALL LoadResources(ResName$,hRes%)
'
' Creating a Menu from the MENU2 Script.
'
MenuName$="MENU2"
CALL OpenMenuRes(hRes%,0,MenuName$,hMenu%)

'
' Setting the new Menu in the current Session.
'
CALL SetMenu(hMenu%)

'
' Event Loop.
'
GetMsg%=1
WHILE GetMsg% <> 0
CALL GetMessage(hWndMsg%,Msg%,wP%,XCursor%,YCursor%,
XParam%(1),Command$)
IF Msg% <> 0 THEN
'
' A message is available
'

' Message due to a Menu Item. wP contains the activated Item ID.
IF Msg% = WMCOMMAND% THEN
PRINT " WMCOMMAND: ID of the selected Item: ";wP%
END IF

'
' Message sent by the System Menu of the Session. wP is the activated
' Item ID.
'
IF Msg% = WMSYSCOMMAND% THEN

'
' The Close Item has been activated.
'
IF wP% = SCCLOSE% THEN
Txt$="Do you really want to end this Demo ?"
Caption$="MessageBox"
CALL MessageBox(0,Txt$,Caption$,MBYESNO%,Code%)
IF Code%=IDYES% THEN GetMsg%=0
END IF
END IF
ELSE
'
' No message is available, this application is idle.
'
CALL ReleaseTimeSlice
END IF

WEND

CALL EndExecution


Windows and Graphics

The PBDK offers a very simple access to windows because it does all the tedious work to maintain, move, repaint and restore your windows. You just have to create them and then use them for painting or drawing. Dolce Vita provides a full and simplified access to the True Type fonts.

Related Topics:

Sessions and Windows

Creation of a Window

Painting a Window

Fonts


Sessions and Windows

All the Windows of a DV application are automatically created in a Session, which acts like the Working Area of an application. Therefore, they can be all moved, iconized or maximized at the same time. This organization makes it easy to let several DV application work at the same time, in their own separate Sessions. A DV application requiring windows must first open a Session. The same rule applies to Menus.


Creation of a Window

A Window creation is very similar that of a Dialog Box or even to a Control creation. The CreateWindow function requires basically the same set of parameters:

A Style, choosing the attributes of a Window.

A Text, to be displayed in the Caption Bar.

The Position and Size of the Window to open.

It returns a Handle of the new Window. (See code below)


Painting a Window

An application can paint and draw in a Window as soon as it is created. All the graphic functions require as first parameter the Handle of the Window where to draw. (See Figure 1.7)

Figure 1.7: A first Window

Example 1.8: Creating Windows

CALL InitExecution("DIALOG",RESETAPP%)
CALL ReadErrorNumber(DVError%)
IF DVError% > 0 THEN END
'
' Creation of the Session.
'
Title$="Session Title"
CALL OpenSession(Title$,8,8,400,250,hSession%)

'
' Creation of a Window.
' This Window will be given a Caption Bar, a MinimizeBox, a resizable
' Frame and a System Menu (Style).
'
Style&=WSCAPTION& OR WSMINIMIZEBOX& OR WSTHICKFRAME& OR
WSSYSMENU&
Title$="A First Window"
CALL CreateWindow(Style&,Title$,16,8,320,200,hWnd%)

'
' Loading a BMP file.
' LoadPixmap returns in hBmp the handle of the loaded Bitmap.
'
BmpName$="CLOWN16.BMP"
CALL LoadPixMap(BmpName$,hBmp%)
'
' Painting the hBmp Bitmap in the hWnd Window.
'
CALL PaintPixMap(hWnd%,hBmp%,0,0,320,200,SRCCOPY&)

CALL EndExecution

Figure 1.8: A Window displaying a True Type text.

Once you have created the Window and filed it with the loaded Bitmap, you can move it or iconize it or its Session: Dolce Vita does all the work to maintain and repaint these objects for you.


Fonts

Dolce Vita provides full and simplified access to the MS Windows fonts, including True Type. A DV application can scan the available Fonts of your MS Windows configuration, select one and use it to perform text drawing operations in its windows or to the printer, to change the font of its Controls, and so on.

The following sample shows how to scan, select and record a Font, and then how to use it to display a string in a window (See Figure 1.8).

Example 1.9: Windows and Fonts

CALL InitExecution("DIALOG",RESETAPP%)
CALL ReadErrorNumber(DVError%)
IF DVError% > 0 THEN END
'
' Creating a Session.
'
Title$="Session Title"
CALL OpenSession(Title$,8,8,400,250,hSession%)

'
' Creating a Window.
'
Style&=WSCAPTION& OR WSMINIMIZEBOX& OR WSTHICKFRAME& OR
WSSYSMENU&
Title$="Another Window"
CALL CreateWindow(Style&,Title$,16,8,320,200,hWnd%)

'
' Painting the new Window in gray.
'
'
' All the colors required by Windows are 24 bits colors. Dolce Vita
' provides functions to build such colors from their Red, Green and
' Blue components. For instance, a (192,192,192) RGB combination
'
CALL SetRGB(192,192,192,FColor&)
CALL SetRGB(0,0,0,BColor&)
'
' Selecting the current foreground and background colors of the hWnd
' Window.
'
CALL SetWindowColors(hWnd%,FColor&,BColor&)
'
' Filling the hWnd Client Area with the current foreground color.
'
CALL PaintRectangle(hWnd%,0,0,320,200,0)

'
' Scanning the list of available Fonts
'
'
' GetFontCount returns the number of available Fonts.
'
CALL GetFontCount(FontCount%)
'
' Scanning the list of Fonts.
' The application stops scanning the list when it finds the first Arial
' Font.
'
DIM LogFont%(13)
FaceName$="     "
FOR i%=0 TO FontCount%-1
CALL GetFont(i%,FaceName$,LogFont%(1))
IF FaceName$="Arial" THEN GOTO BREAK
NEXT
BREAK:
'
' Modifying a few of the properties of the found Font: Size, Italic,
' Underline.
'
' Setting the required Font Width
LogFont%(lfWidth%)=16
' Setting the required Font Height
LogFont%(lfHeight%)=32
' Setting the Italic flag *)
LogFont%(lfItalic%)=1
' Setting the Underline flag
LogFont%(lfUnderline%)=1
'
' Recording the chosen and modified Font. CreateFont returns in hFont
' the Handle of the recorded Font. This Handle will be required by the text
' display function (TextOut).
'
CALL CreateFont(FaceName$,LogFont%(1),hFont%)
'
' Creating the foreground (Color) and background (BackColor) colors to be
' used to display the text.
'
CALL SetRGB(255,0,0,FColor&)
CALL SetRGB(192,192,192,BColor&)
'
' Displaying the text in the hWnd Window, using the hFont Font.
'
Txt$="Dolce VitaCALL "
CALL TextOut(hWnd%,hFont%,16,16,FColor&,BColor&,Txt$,DX%,DY%)

'
' Destroying the recorded Font.
'
CALL DeleteObject(hFont%)

CALL EndExecution

The method explained in this code for managing Fonts is generic. The steps involved in the creation of a Font are always the same:

Read the number of available Fonts (GetFontCount).

Scan the list of these Fonts and read their properties (GetFont).

Once you have found the right Font, record it and save its Handle
(CreateFont).

When the recorded Font is no longer used, destroy it (DeleteObject).

Once you have created the Window and displayed text using a given Font, you can move it or iconize it or its Session. Dolce Vita does all the work to maintain and repaint these objects for you.


Getting Started - Printing
Printing

Drawing or painting in a Window or with the Printer involves the same code. The graphic functions apply exactly the same way. They all require as their first parameter the Handle of the object to be used. The Handle of a Window is obtained at creation time. The Printer has to be opened to get its Handle before it can be used.

Example 1.10: Printing

CALL InitExecution("DIALOG",RESETAPP%)
CALL ReadErrorNumber(DVError%)
IF DVError% > 0 THEN END
'
' Reading the name of the default Printer.
'
Driver$=SPACE$(32)
Mode$=SPACE$(32)
Port$=SPACE$(32)
CALL GetPrinterInformation(Driver$,Mode$,Port$)
'
' Using the Driver, Mode and Port values returned by
' GetPrinterInformation to open the Printer. OpenPrinter
' returns in hPrinter its Handle.
'
CALL OpenPrinter(Driver$,Mode$,Port$,hPrinter%)

'
' Reading the capabilities of the opened Printer. (HSize,VSize) gives
' the size, in millimeters, of the printing page. (HRes,VRes) gives its
' resolution, in pixels.
'
CALL GetPrinterCapabilities(HSize%,VSize%,HRes%,VRes%)

'
' Loading a BMP file. hBmp receives the Handle of the loaded Bitmap.
'
BmpName$="CLOWN16.BMP"
CALL LoadPixmap(BmpName$,hBmp%)

'
' Computing the rectangle size in the printing page where to paint the
' loaded pixmap.
'
Left%=HRes% / 4
Top%=VRes% / 4
DVWidth%=HRes% / 2
Height%=VRes% / 2

'
' Painting the hBmp bitmap on the hPrinter Printer.
'
CALL PaintPixMap(hPrinter%,hBmp%,Left%,Top%,DVWidth%,Height%,
SRCCOPY&)

'
' Deleting the hBmp Bitmap.
'
CALL DeleteObject(hBmp%)

'
' The printer is closed, it forces the printing job to be performed.
'
CALL ClosePrinter(NOABORT%)

CALL EndExecution

Comments

The method explained here to manage the Printer is generic. It can be reused as is in any other application:

Read the name of the current default Printer (GetPrinterInformation).

Use this information to open the printer (OpenPrinter), and save its Handle.

Read the physical properties of the opened Printer (GetPrinterCapabilities).

Use any graphic function with the Printer Handle the same way you would in a Window. (PaintRectangle, TextOut, PaintPixmap...)

Close the Printer to have the pending job performed (ClosePrinter).


Conclusion

The samples presented in this chapter have introduced to you most of the principles you will have to master in order to create real Windows applications with Dolce Vita.

They show that creating such different objects as Dialog Boxes, Controls, Windows and Menus is done by very similar functions. They also show that receiving and treating the user's input on these objects relies on a very general structure.

Most of these examples provide generic code that can be duplicated and enriched to build real applications.

A good understanding of these few pages will make the learning of the rest of Dolce Vita easy.