## Angry Red Planet # Kernel Library |

The ArpKernel library is a miscellaneous collection of classes that are useful in a lot of other places and/or don't warrant a library of their own. Not all of the classes are described here: there are a number that are still under development, archaic, or simply not very useful, which would not be too worthwhile to include in any documentation beyond their existing source code.

# Classes

## ArpAboutView (header file)

This is a subclass of BView that implements Angry Red Planet's standard animated "about" box. It is given the program's title, version, and lines of text describing the application, and generates a view with the ARP logo and description text animating around it.

## ArpAboutWindow (header file)

A thin subclass of BWindow that contains an ArpAboutView as its single child. This makes it possible to bring up a full "about" box with a couple lines of code.

## ArpAddonManager (header file)

This class keeps track of a set of add-ons in which a program is interested. It is derived from ArpMultiDir, providing all of that class's functionality of searching through multiple directories for files. On top of that, the ArpAddonManager keeps track of the add-ons it finds and provides an interface for accessing them.

The ultimate intention is to have this also perform a watch on the directory to see any new additions to the available add-ons, but that functionality is not yet implemented.

## ArpColor (header file)

This is a small wrapper around the rgb_color structure, making it more natural to use in an OO world.

## ArpConfigurableI (header file)

This is an abstract interface for an object that can be "configured". It defines methods for getting and setting the objects current state as a BMessage, and a method for creating a set of BView hierarchies that can be presented to the user for manipulating the state of the object.

## ArpConfigureFile (header file)

An ArpConfigureFile contains one or more ArpConfigurableI interfaces for objects that together can be thought of as a complete "configuration set". The class provides operations that you can do on this set of configurable objects: extract all of their currently settings into a single BMessage, apply a previously created settings BMessage to the objects, and read and write these BMessage settings from and to files. In addition, when a settings file has been associated with the object, you can be supplied node monitor messages when that file changes.

## ArpConfigureImpl (header file)

This is a helper class that provides a standard implementation for configuration views. By using this class, all you need to do to implement a configuration view is to create the controls in your view, and then call the ArpConfigureImpl AttachedToWindow(), DetachedFromWindow(), and MessageReceived() methods in the cooresponding places in your view.

Currently, this class only provides implementations for BCheckBox (bool and int32 parameters) and BTextControl (string and int32 parameters) objects.

## ArpConfigurePanel (header file)

There are actually two classes in this file. The class it is named for, ArpConfigurePanel, is-a BTabView that automatically generates its tabs from an ArpConfigureFile's ArpConfigurableI interfaces that are passed to it. The second class, ArpConfigureView, places an ArpConfigurePanel in a larger view with tools for managing the state of the configurable objects. With this second class, almost all of the details of creating "settings"-type windows is automatically done for you.

## ArpConfigureWatch (header file)

This is a helper class for inplementing ArpConfigurableI classes that can have configuration views changing and watching them. Currently, this involves managing a set of configuration views that are registered as watching your own configurable view. To use this class, all you need to do is call its MessageReceived() function to handle the messages these views will send to you.

## ArpDebug (header file)

In this file are a set of macros that are used by the rest of the ARP class libraries to produce debugging output. The output is iostream-based, and this file includes additional definitions for writing some common object (such as BRect and BMessage) to an output stream.

## ArpDocumentButton (header file)

This is a widget for a "document drag and drop" button. The button acts like a normal button, where presses will be set as a BMessage to the target you select. In addition, the class can act as an intermediate for drag-and-drop operations, providing a drag-and-drop interface for opening and saving documents.

## ArpMessage (header file)

This is a small wrapper around the BMessage class. It has two main purposes:

- New methods are added for finding and adding BFont objects and rgb_color structures.
- A new interface for getting and setting values in a message is defined, which is intended to make constructing ArpLayout hierarchies easier. They are based on the idea of having the "set" function return a reference to the ArpMessage it was called on, so multiple sets can be batched up together.

  For example, a function that requires a single argument that is a BMessage with some parameters could be called with:

  >     MyFunc(ArpMessage()
  >                .SetInt32("SomeParamter", 14)
  >                .SetString("SomeOtherParamter", "aValue")
  >            );

In addition, this class defines a new type -- `ARP_INDIRECT_TYPE` -- that is used by the ArpLayout library to implement its "global values".

## ArpMultiDir (header file)

This is-a BDirectory that actually contains multiple directories, usually representing a "search path". It overrides the BDirectory interface to make these all look like one big directory to the rest of the world, so that they don't have to worry about which or how many directories they are supposed to be looking through.

## ArpNotificationRegistry (header file)

This class stores a list of BHandlers that have an "interest" in some piece of data. When the owner of this class wants to, it can ask the ArpNotificationRegistry to report a change to all of its interested BHandlers.

## ArpRef (header file)

This file contains various pieces for reference counted objects. It contains the following classes:

ArpBaseRef
  A common base class for anything that is going to hold a reference on an object. It is primarily useful for debugging: objects are given this class when their reference count is changes, to they can track who is holding them, and it contains a string identifier naming the holder.
ArpRef and ArpCRef
  These are template classes that implement a "reference counting pointer". That is, they look and feel like a pointer to the object they are templatized on (or a const pointer, in the case of ArpCRef), but assigning objects to them automatically calls the AddReference() and RemReference() as appropriate. By using these classes, you pretty much never need to call the reference functions directly yourself, avoiding a lot of bugs that happen in keeping track of reference counts.
ArpRefableI
  This is an abstract interface that an object that wishes to be reference counted (and work with the above classes) must implement.
ArpRefable
  A generic implementation of the above interface.

## ArpString (header file)

Our own implementation of a string class. This was written long before BString existing, and may never have been written if there had been a BString back then. On the other hand, it provides a number of features that I believe BString doesn't:

- You can store static literals in an ArpString, without having to copy them.
- Its internal string buffer implementation tries to avoid copying string data when assigning one ArpString to another.
- It fully supports strings with embedded \0 characters.
- A NULL string pointer is considered a valid value by ArpString, and can be assigned to it and retrieved again.

In addition, there are some helper classes in this file to help in dealing with ArpString objects:

ArpStrTok
  An OO implementation of strtok(). Takes advantage of the ArpString buffer copying feature to help in reducing the number of string copies while still being non-destructive of the input string.
ArpParseUrl
  A simple function that extracts the various fields from some common URL forms.
ArpUnescapeURL
  Parses URL escape sequences in a string.

# Copyright

All files and code contained in this package are Copyright ©1998 Angry Red Planet, except where otherwise noted.

The files contained here-in are distrubuted under a modifed form of the Artistic License. See the file `@License.html` or `@License.txt` for a copy of this license.