view release on metacpan or  search on metacpan

tvision.git/examples/palette/README.md  view on Meta::CPAN

## How it works

So, how does one actually get a particular color from the palette
inside the draw member function of a view?  The answer lies in
understanding in greater detail how a given palette is related to
its parents.

Every class derived from `TView` (which means *every visible Turbo
Vision object*) has a color palette.  The palette may be inherited
(like `TApplication`) or it may be `NULL` (like `TDeskTop`) but all
views do have one.  The virtual function `getPalette()` is used to
supply the palette for each view. It is important to realize that
this particular function is never called explicitly by the
programmer; it will be called by Turbo Vision when necessary.

The member functions of `TView` that actually do write to the view,
with one exception, all take a color index as one of their
parameters.  This parameter must be thought of as the value of an
index to a style, not the actual color.

For example, When using `TView::writeStr()`, one parameter
specifies a color index.  Inside of `writeStr()` the following
procedure is applied to convert this index into an actual color
value.  The current view's palette is examined at the specified
index entry and a value `X` is found there.  Next, the view's
owner's palette is retrieved and `X` is used as an index into this
palette where another value `Y` resides.  This process continues
until the view being examined no longer has an owner.  At this
time, the value at the current index is returned and interpreted
as a standard PC color attribute byte.

## Example

Here are the palettes for the classes in the enclosed example and
how they map into each other:
```
                          x01   x02   x03   x04   x05   x06
   ┌────────────────────┬─────┬─────┬─────┬─────┬─────┬─────┐
   │TTestView           │ x09 │ x0A │ x0B │ x0C │ x0D │ x0E │
   └────────────────────┴─────┴─────┴─────┴─────┴─────┴─────┘
                           â–¼     â–¼     â–¼     â–¼     â–¼     â–¼
                 x01-x08  x09   x0A   x0B   x0C   x0D   x0E
   ┌────────────┬───────┬─────┬─────┬─────┬─────┬─────┬─────┐
   │TTestWindow │  ...  │ x88 │ x89 │ x8A │ x8B │ x8C │ x8D │
   └────────────┴───────┴─────┴─────┴─────┴─────┴─────┴─────┘
                           â–¼     â–¼     â–¼     â–¼     â–¼     â–¼
                 x01-x87  x88   x89   x8A   x8B   x8C   x8D
   ┌────────────┬───────┬─────┬─────┬─────┬─────┬─────┬─────┐
   │TTestApp    │  ...  │ x3E │ x2D │ x72 │ x5F │ x68 │ x4E │
   └────────────┴───────┴─────┴─────┴─────┴─────┴─────┴─────┘

                                Table I
```

All numbers used in the palettes in this document are in
hexadecimal (it is easier to understand attributes in that base).

Here is a concrete case of a "palette" walk, taken from the code
supplied with this document.  Suppose there is a view of type
`TTestView` inserted inside a window of type `TTestWindow`, itself
inserted in the desktop.  The palettes for these views are shown
above.  To draw something with color `0x01`, simply use `0x01` as the
parameter to the write functions used in `TTestView::draw()`.
`TTestView`'s palette contains the number `0x09` at index `0x01` and
`TTestView`'s owner is `TTestWindow`.  Index `0x09` in `TTestWindow`'s
palette contains `0x88`.  `TTestWindow`'s owner is `TDesktop` which has
a `NULL` palette and is skipped (see notes). `TDesktop`'s owner is
`TTestApp` and it's palette contains `0x3E` at index `0x88`.  So the
color that will be used is `0x3E` or yellow on cyan.

The `writeXXX` functions in TView all take color index values in
the current palette except one, `writeLine(..., TDrawBuffer)`.  A
`TDrawBuffer` is a buffer for an entire line.  Once constructed, it
is drawn into the view using `writeLine()`.  `TDrawBuffer`'s member
functions for drawing are quite similar to `TView`'s with one
exception.  They do NOT use color index values.  They use
attribute bytes to determine the colors used. What this means is
that in order to use the color palettes, one must obtain the
color attribute for a member of the current palette by hand. This
is done with the function `getColor()`.  Pass it the index and it
performs the "palette walk" and returns the actual attribute
represented.  Use this value in `TDrawBuffer`'s write functions.

Note that any attribute byte can be used with a `TDrawBuffer`.
`getColor()` need not be the source of the value used.

<div id="construction"></div>

## Palette construction

Creating a new palette for a given view is quite simple, though
deciding what indexes to use may take some thought.  It requires
inheriting from the view and overriding the `getPalette()` member
function.  This function has the following prototype:

```c++
TPalette& TTestView::getPalette() const;
```

The actual palette is a character string where the bytes contain
the appropriate reference values.  These bytes are normally
written out in hex when the string is created.  For example,

```c++
#define cpTestView "\x9\xA\xB\xC\xD\xE"
```

is the definition of the palette for `TTestView`.  The `cpTestView`
symbol is then used in TPalette constructor like this:

```c++
TPalette palette( cpTestView, sizeof(cpTestView)-1 );
```

The subtraction of 1 from `sizeof()` is to remove the terminating
`NULL` that all C++ literal strings have by default.  Also, since a
reference to this palette is returned by `getPalette()`, it must
exist from the first call to `getPalette` onward and is normally
made a static local variable to function (to avoid polluting the
global name space).  So the entire function looks like this: