Roadmap


Contents

1 Twokindsofcomponents
2 Commands
3 Views
4 Overview
5 Tableofcontents

1 Two kinds of components

BlackBox contains a component framework, which is a new concept for most programmers. This document gives a quick overview over which kinds of BlackBox components there are, when you need which, and where the documentation is.
Generally, BlackBox distinguishes two major categories of components: commands and views. Commands are comparable to traditional scripts or macros, except that they are implemented in a "real" programming language, rather than in a limited or inefficient special purpose scripting language. This means that if a problem grows, its programmatic solution can grow along; you'll not suddenly need to switch to another language. Thus commands range from simple automation tasks to complex programs such as compilers. The main purpose of commands is to assemble visual objects, i.e., to make them work together. Views are the visual objects of the BlackBox Component Framework.

2 Commands

Often, programs are built around data entry masks; these are forms in BlackBox. Module Controls and the form subsystem provide the necessary support to build form-based user interfaces.
Often, you'll also want to generate texts, e.g., for reporting purposes. You can use all capabilities of the BlackBox text subsystem, including fonts, type sizes, color, embedded components such as stamp views or link views, and so on. An example command which uses both the form and text subsystems is ObxOrders.
Before looking at this advanced example, you may want to have a look at simpler text and form sample programs. The Obx subsystem ("Overview by Example") provides a variety of such examples.
BlackBox programs are document-centric. This means that you typically work with documents and document parts; and not directly with files or windows. Files are used only for simple databases or for manipulating legacy data. Sometimes it's possible to convert legacy data to a BlackBox data type by writing a new converter. Obx also contains an example of such a converter.

3 Views

If the built-in subsystems are not sufficient for your purposes, you need to develop a new BlackBox component. Usually this is a document component, a so-called view implementation. In contrast to old-style programs, a view only owns a part of a document, and not the whole screen or even a whole window. If the view is the outermost view (root view), the result cannot be distinguished from a traditional application. However, a view is always able to be embedded in texts, forms, and so on. 
Examples of views are text views; form views; link views (hypertext); stamp views (time stamps); clock views; Oberon microsystems logo views; bitmap (picture) views; commander views (buttons which execute a command); fold views; error views generated by the compiler; various controls (command buttons, check boxes, edit fields, ...) and so on. Before implementing your own view type, take a look at these views to get an idea of the variety of ways in which views can be used. Sometimes it's not necessary to implement a whole new complex subsystem in order to solve a problem, but rather some additional view which extends the functionality of the existing text subsystem, for example.
Views may or may not have a model. A model is the datastructure which is visually represented by the view. In simple cases where the view needs no editable persistent state, no model is needed. Examples are logo views, controls, etc. Full-fledged editors on the other hand should contain a separate model. Such more complex views are typically implemented in several modules, while simple views without separate modules are usually implemented in a single module.
Advanced views may contain other views. Such advanced views are called containers. There are three useful categories of containers:
• A Wrapper contains another view and modifies or extends its behavior. Typically, a wrapper has the same size as the wrapped view. For example, a terminal view may wrap a standard text view; it adds the communication facilities, while the text view provides the echoing of communicated text.
• A Special Container contains one or several embedded views. The container knows about the types of the embedded views and their layout. Views cannot be inserted or deleted. For example, such a special container could have a query view at the top where database queries can be typed in, and a larger text view at the bottom where the results of the query appear. Another example is given in ObxTwins.
• A General Container may contain an arbitrary number of embedded views, and they may change over time. This is the most general and most complex kind of view, e.g., the built-in text and form subsystems. The form subsystem is available in source form. Examples for the other kinds of view are available as Obx examples.

Views may have no programming interface, a simple procedural interface (typically based on properties, see Controls), or a full-fledged extensible interface. For the latter, it is recommended that the exported interface is separated from the hidden default implementation; in order to achieve maximum extensibility.

4 Overview

How should you start to get acquainted with BlackBox? We suggest that you start with the introduction texts A Brief History of Pascal and GuidedTour.
The documentation consists of four major parts:
•A user manual that describes the user interface and most important commands of the BlackBox Component Builder
•A tutorial that first introduces the general BlackBox design patterns (chapters 1 to 3). Graphical user interfaces, forms, and controls are discussed in chapter4. The text subsystem is explained in chapter5. The remaining chapter6 deals with view programming.
•Overview by Example is a rich source of examples, ordered by category and difficulty.
•The programmer's reference consists of one documentation file per module. Each subsystem has a Sys-Map text which contains links to the individual texts.
Apart from the Obx samples and the tutorial examples, another documentation for the most important kinds of BlackBox programs is available in Dev/Rsrc/New. These are template documents that you can use as basis for your own programs. The template documents' module names are renamed automatically by the Tools->CreateSubsystem... command. This command also creates a suitable new subsystem directory structure (see DevSubTool).
Programmers who need to interface with non-BlackBox software should consult the text Platform-SpecificIssues.
Note that you can reach the entire on-line documentation via the help menu, or from the table of contents below.

5 Table of contents

Quick Start
GuidedTour
OverviewbyExample

Tutorial
Table of Contents
1 UserInteraction
2 CompoundDocuments
3 DesignPractices
4 Forms
5 Texts
6 ViewConstruction
Appendix A: ABriefHistoryofPascal
Appendix B: FromPascaltoComponentPascal

User Manuals
Framework
TextSubsystem
FormSubsystem
DevSubsystem
StdSubsystem

Developer Manuals
Framework
TextSubsystem
FormSubsystem
DevSubsystem
SqlSubsystem

Component Pascal
LanguageReport
What'sNew?
CharacterSet
DocumentationConventions
ProgrammingConventions

Miscellaneous
License
Contributors
Platform-SpecificIssues
Ctl Subsystem
