About Examples

The Examples directory contains sample code that illustrates the use of selected CommonPoint(TM) application system frameworks. The code ranges from single functions to small programs of half a dozen classes. All the code can be examined, copied, and executed.

An index to README files can be found in Examples.

Sample directory organization

The code is organized into directories according to subsystem. These groupings roughly mirror the taxonomy, without the full structure of the taxonomy. Within each directory are a number of subdirectories; each subdirectory builds a project.

Snippets and samples

Snippets

Snippets are functions that illustrate how to instantiate and call CommonPoint classes and functions to achieve particular effects. For convenience, related snippets are organized into snippet classes. Each such class has its own pair of .h and .C files named after the class; there might be several classes per project.

For example, the text snippets project is found in the directory Examples/Text/TextSnippets. This project contains the style, transcoding, and text iteration snippets, organized into the following classes: TStyleSnippets, TTranscodingSnippets, and TTextIterationSnippets. Each class is defined in its own pair of .h and .C files-- StyleSnippets.h and StyleSnippets.C, and so on. The snippet for modifying style data can be found in StyleSnippets.C as a member function of TStyleSnippets, ModifyStyleData.

Snippets can be executed using the RunSnippet or SnippetBrowser utilities. These utilities can be found in the SharedLibs directory. Information about these utilities, and additional information about the snippet base class TSnippets, can be found in ExampleUtilities.

Samples

Samples are complete programs. Each sample is a separate project and resides in its own directory. Often there are several samples illustrating various features of a single framework, organized as numbered subdirectories of a parent directory.

The notification samples, for example, are separate projects, organized as subdirectories of Examples/Notification. These projects are numbered to order simpler samples before complex ones. For example, 01.BasicNotification is a subdirectory containing code that illustrates the simplest use of the notification framework, while 06.RemoteNotification presumes knowledge of communications and RPC, as well as passing knowledge of some earlier notification samples. In a series of samples like these, often the same classes appear over and over, slightly modified each time. It is advantageous to examine the samples in order, since information introduced in earlier samples is not discussed in later ones.

README Files

Each directory contains a README file describing the contents of that directory. The information in these files is intended to be a quick reference to the contents of the directory, not a comprehensive description of the sample or subsystem. Subsystems are documented in the CommonPoint information set, not in the README files. The snippets and samples have no additional documentation.

Makefiles

Each directory contains a .PinkMake file for that directory. The higher level directories simply reference the subdirectories as subprojects, but the leaf directories build binaries, libraries, or servers as appropriate.

Makefiles for snippets build the sample classes into a library. To execute the snippets you need to use either the RunSnippet or SnippetBrowser utility applications.

Makefiles for samples generally build either document components or binaries. Components are provided with scripts that invoke RunDocument to launch the document. Both binaries and these scripts follow a naming convention of ending in App and can be executed directly.

Executing examples from a shell

As mentioned above, binaries and component scripts are directly executable, and follow a naming convention of ending in App to make them easily recognizable. Servers that are part of a sample will be automatically started as needed; you should not need to start them directly. Because they often display progress information to the shell, samples are typically run from a shell.

Snippets may be executed from the shell using the RunSnippet utility, found in SharedLibs. Currently the default way to use it is as follows:

RunSnippet ClassName PackageName  //  lists all the snippets in that class, if the class is found.
RunSnippet ClassName PackageName -n 1  // executes the first snippet
RunSnippet ClassName PackageName -n 1 -s  // displays source for the snippet, then executes it as above
RunSnippet  // displays a brief summary of all options

Only a few snippets are fully usable via RunSnippet. The text snippets that modify styles, for example, cannot display the styled text in a terminal window. So to run them a special utility, SnippetBrowser, is provided.

Executing snippets from the CommonPoint environment

The SnippetBrowser script (found in SharedLibs) launches a program that allows you access to the snippets. SnippetBrowser provides a menu hierarchy that lets you execute each snippet and see the output and the source code for the snippet in a scrolling window.

Installing RunSnippet and SnippetBrowser

Headers and libraries for RunSnippet and SnippetBrowser are in /TaligentSamples/Supported/Enablers/ExampleUtilities. No source for them is provided. Building the project in this directory will export the libraries to SharedLibs and the headers to $TaligentRoot/Includes/Samples. These headers and libraries are required by most of the snippets and samples.

This project is usually built as part of the installation process; you will only need to rebuild it if you need to reinstall the examples.

Stopping an example

Snippets run from the shell should stop of their own accord when they complete. In the event of an error, kill -9 [pid] is always available.

If you are running the SnippetBrowser program, you can just close the main window to stop it.

Current status

These examples all run with version 1.0 of the CommonPoint environment.

Click the icon to mail questions or corrections about this material to Taligent personnel.