Short BOOPSI Overview

Grzegorz Kraszewski

---

This article in other languages: Polish

Object Oriented Programming

Object oriented programming is a technique developed as a response to two trends in the computer market. The first one was increasing complexity of software. Management of a traditionally written codebase becomes harder when the code size increases. The second trend was the increasing popularity of graphical user interfaces, which meant the end of sequential execution of programs. Instead modern programs are event driven, which means the flow of code execution is determined by external events (like user input) and is not known at the time of writing the program. Object oriented programming divides a program into a set of objects interacting with each other using well defined interfaces. Such a modularization simplifies the management of a software project and also fits naturally with the concept of modern graphical user interfaces. User controls (called "gadgets" in MUI) are just objects in the code and they interact with other objects representing user data.

This short introduction is not intended to be a complete lecture on object oriented programming. On the other hand no knowledge of any particular object oriented programming language is required to get familiar with BOOPSI. Usually the support for OOP techniques comes with a programming language, which is either designed for OOP (like C++, C# or Java) or has OOP support added in a more or less logical way (Objective C, PHP). This is not the case for BOOPSI and MUI however. In this case object oriented programming support comes from the operating system. BOOPSI and MUI can be used with any programming language, including traditional ones, for example C and even assembler.

The BOOPSI module is located in the intuition.library, with some important functions being added from a statically linked libabox. Its primary design goal was to build a framework for wrapping Intuition GUI elements in an object oriented interface. This approach was unfortunately not flexible enough, so MUI uses only the basic BOOPSI framework. This framework provides the four basic concepts of object oriented programming: classes, objects, methods and attributes. It also supports class inheritance. Because of its simplicity, BOOPSI is easy to understand and use, especially when compared to more sophisticated frameworks, like the one in the C++ programming language.

Classes

A class is the basic term of object oriented programming. It is the complete description of its objects, their attributes and methods. In the BOOPSI framework, a class consists of:

• An IClass structure. A pointer to this structure is used as a reference to the class. The IClass structure is defined in the <intuition/classes.h> system header file. There is also the Class type, which is the same as struct IClass.
• A class dispatcher function. When an application calls a method on an object, the object's class dispatcher is called. The dispatcher checks the method's identifier and jumps to this method code. The dispatcher is usually implemented as a big switch statement. For simple classes, which implement only a few short methods, code of these methods is often placed inside case statements. Bigger classes have methods' code separated into functions placed outside of the dispatcher. As every method goes through a dispatcher, all BOOPSI methods are virtual in the C++ meaning. For this reason, calling a method in BOOPSI is usually slower than in C++.

A class defines a set of methods available for its objects (instances) by the set of case statements in the dispatcher. Object's attributes are set using the OM_SET() method and are gotten using OM_GET(). The attributes may also be passed to the object constructor directly. The set of attributes for a class and applicability of the attributes are then defined by the source code of OM_NEW() (the constructor), OM_SET() and OM_GET() methods. There is no formal declaration of class. There is also no division between public and private methods and attributes. Some kind of formal declaration and levels of access may be imposed by putting every class in a separate source code file. An accompanying header file would contain definitions of method identifiers, attribute identifiers and method parameters structures, but only those considered "public". Private method identifiers should be defined inside the source code of the class, so they are not visible outside of the class source code.

A BOOPSI class can be shared between applications. All the MUI built-in classes are shared ones. The BOOPSI maintains a system-wide list of public classes (the list can be browsed with the Scout monitoring tool). Shared classes are identified by names. A part of the MUI standard classes is contained inside the main MUI library – muimaster.library. The library adds these classes to the system list when opened for the first time. The rest of the MUI standard classes are stored on the system disk partition in the MOSSYS:Classes/MUI/ directory. Additional third party classes may be placed in the SYS:Classes/MUI/ directory.

Shared classes use the MorphOS shared library framework, in other words a shared BOOPSI class is just a kind of shared library. The class adds itself to the public list of classes, when it is opened from disk. As such, a BOOPSI shared class should be opened with OpenLibrary() before use (see details), especially as BOOPSI classes are usually not included into the list of libraries opened automatically. This is not the case for MUI classes however. MUI shared classes can be used without opening them. It is explained below, in the MUI Extensions to BOOPSI section.

Methods and Attributes

Methods

Methods are just actions, which can be performed on an object. A set of available methods is defined by the object's class. Technically speaking, a method is a function called with an object as its parameter in order to change the object's state. In BOOPSI, methods are called using the DoMethod() call from libabox:

result = DoMethod(object, method_id, ... /* method parameters */);
result = DoMethodA(object, method_struct);

The first, more popular form of the call just builds the method structure on the fly, from arguments passed to it. Any method structure always has the method identifier as the first field. The DoMethodA() call gets a pointer to the method structure, the structure is built by the application. The second form is rarely used. The number and meaning of parameters, as well as the meaning of the result are method specific. Comparison of executing a method with both forms of the call is given below:

struct MUIP_SomeMethod
{
  ULONG MethodID;
  LONG ParameterA;
  LONG ParameterB;
};

DoMethod(object, MUIM_SomeMethod, 3, 7);

struct MUIP_SomeMethod mparams = { MUIM_SomeMethod, 3, 7 };
DoMethodA(object, &mparams);

The DoMethod() form is more convenient, so it is commonly used. MUI uses specific prefixes for all its structures and constants:

• MUIM_ for method identifiers.
• MUIP_ for method parameter structures.
• MUIA_ for attribute identifiers.
• MUIV_ for special, predefined attribute values.

The C types used in the method structure above may need some explanation. LONG is a 32-bit signed integer, ULONG is an unsigned one. Because the structure is usually built on the processor stack, all parameters are extended and aligned to 32 bits. Then every parameter in the structure must be defined either as a 32-bit integer or a pointer. Any parameter larger than 32 bits must be passed via pointer (for example double precision floats or strings).

Setting an Attribute

An object's attributes represent its properties. They are written and read using special methods, OM_SET() and OM_GET() respectively. This differs from most object oriented programming languages, where attributes (being implemented as an object's fields) are accessed directly. Manipulating attributes in BOOPSI is slower then, as it implies performing a method.

The OM_SET() method does not take a single attribute and its value, but a taglist of them, so one can set multiple attributes at once. The setting of two attributes to an object may be done as follows:

struct TagItem attributes[] = {
  { MUIA_SomeAttr1, 756 },
  { MUIA_SomeAttr2, 926 },
  { TAG_END, 0 }
};

DoMethod(object, OM_SET, (ULONG)attributes);

However, this is cumbersome and the code is not easily readable. The intuition.library makes it easier by providing the SetAttrsA() function, which is a wrapper for the OM_SET() method. Using this function and the array defined above, one can write:

SetAttrsA(object, attributes);

It still requires definition of a temporary taglist, but the function also has a variadic (meaning it can take a variable number of arguments) form SetAttrs(), which allows for building the taglist on-the-fly:

SetAttrs(object,
  MUIA_SomeAttr1, 756,
  MUIA_SomeAttr2, 926,
TAG_END);

This is not all however. Programmers are lazy and decided that in the common case of setting a single attribute, SetAttrs() is still too much typing. A common practice found in sources using MUI was to define an xset() or set() macro, which is now defined in the system headers, in the <libraries/mui.h> file.

#define set(object, attribute, value) SetAttrs(object, attribute, value, TAG_END)

Then, setting a single attribute can be coded as follows:

set(object, MUIA_SomeAttr1, 756);

The OM_SET() method returns the number of attributes applied to the object. If some attributes are not known to the object's class (and superclasses), they are not counted. This return value is usually ignored, it may be used for testing an attribute applicability.

MUI provides a few additional methods for setting attributes, namely MUIM_Set(), MUIM_NoNotifySet() and MUIM_MultiSet(). They are mainly used in notifications.

Getting an Attribute

The OM_GET() method gets a single attribute from an object. There is no multiple attributes getting method. Its first, obvious parameter is the attribute identifier. The attribute value is not returned as the result of the method however. Instead the second parameter is a pointer to a memory area, where the value is to be stored. This allows for passing attributes larger than 32 bits, they are just copied to the pointed memory area. This only works for fixed size attributes. Text strings cannot be passed this way, so they are passed as pointers (a pointer to the string is stored at a place in memory pointed to by the second parameter of OM_GET()). The three examples below demonstrate all three cases:

LONG value1;
QUAD value2;    /* 64-bit signed integer */
STRPTR *value3;

DoMethod(object, OM_GET, MUIA_Attribute1, (ULONG)&value1);  /* integer attr */
DoMethod(object, OM_GET, MUIA_Attribute2, (ULONG)&value2);  /* fixed size big attr */
DoMethod(object, OM_GET, MUIA_Attribute3, (ULONG)&value3);  /* string attr */

In cases when an attribute is returned by pointer, the data pointed to should be treated as read-only unless documented otherwise.

Similarly as for OM_SET(), there is a wrapper function for OM_GET() in the intuition.library, named GetAttr(). This function unexpectedly changes the order of arguments: attribute identifier is the first, object pointer is the second. The three examples above may be written with GetAttr() as follows:

GetAttr(MUIA_Attribute1, object, &value1);
GetAttr(MUIA_Attribute2, object, (ULONG*)&value2);
GetAttr(MUIA_Attribute3, object, (ULONG*)&value3);

The third parameter, a storage pointer is prototyped as pointer to ULONG, so in the first example type casting is not needed.

The <libraries/mui.h> system header file defines a macro get(), which reverses the order of the two first arguments of GetAttr() and adds the typecasting to ULONG*. The order of arguments of get() is the same as for set(), which helps to avoid mistakes. The third line of the above example may be rewritten with get() this way:

get(object, MUIA_Attribute3, &value3);

The most often used attributes are integers (32-bit or shorter) and strings. Both of them fit into a 32-bit variable, as strings have to be passed via pointers. Taking this into account, MUI programmers invented a function (sometimes defined as a macro), which just returns the attribute value instead of storing it at a specified address. The function is named xget() and works as shown below:

value1 = xget(object, MUIA_Attribute1);
/* MUIA_Attribute2 can't be retrieved with xget() */
value3 = (STRPTR)xget(object, MUIA_Attribute3);

The xget() function may be defined in the following way:

inline ULONG xget(Object *obj, ULONG attribute)
{
  ULONG value;

  GetAttr(attribute, object, &value);
  return value;
}

The function is very simple and is compiled to a few processor instructions. That is why it is declared as inline, which causes the compiler to insert the function's code in-place instead of generating a jump. This makes the code faster, albeit a bit bigger. Except for working only with 32-bit attributes, xget() also has the disadvantage of loosing the OM_GET() return value. The value is boolean and is TRUE if the object's class (or any of its superclasses) recognizes the attribute, FALSE otherwise. This value is usually ignored, but may be useful for scanning objects for supported attributes.

The xget() function is not defined in the system headers. It has been described here because of its common use in MUI applications. Its counterparts for bigger sized arguments may be defined if needed.

Object Construction

Having a class, the programmer can create an unlimited number of objects (instances) of this class. Every object has its own instance data area, which is allocated and cleared automatically by the BOOPSI. Of course only object data are allocated for each instance. The code is not duplicated, so it must be reentrant (static variables and code self-modification must not be used).

Objects are created and disposed with two special methods: the constructor, OM_NEW() and the destructor, OM_DISPOSE(). Of course the constructor method cannot be called on an object, because it creates a new one. It needs a pointer to the object's class instead, so it cannot be invoked with DoMethod(). The intuition.library provides NewObjectA() and NewObject() functions for calling the constructor. The difference between them is that NewObjectA() takes a pointer to a taglist specifying initial values for objects. NewObject() allows the programmer to build this taglist from a variable number of function arguments.

NewObject[A]() has two alternative ways of specifying the created object's class. Private classes are specified by pointers of Class type. Shared classes are specified by name, which is a null-terminated string. If the pointer is used for class specification, the name should be NULL, if a name is used, the pointer should be NULL. Four examples below show creating instances of private and public class with both NewObjectA() and NewObject():

Object *obj;
Class *private;

struct TagItem initial = {
  { MUIA_Attribute1, 4 },
  { MUIA_Attribute2, 46 },
  { TAG_END, 0 }
};

A private class, NewObjectA():

obj = NewObjectA(private, NULL, initial);

A private class, NewObject():

obj = NewObject(private, NULL,
  MUIA_Attribute1, 4,
  MUIA_Attribute2, 46,
TAG_END);

A public class, NewObjectA():

obj = NewObjectA(NULL, "some.class", initial);

A public class, NewObject():

obj = NewObject(NULL, "some.class",
  MUIA_Attribute1, 4,
  MUIA_Attribute2, 46,
TAG_END);

NewObject[A]() returns NULL in case of an object creation failure. Usual reasons are: wrong class pointer/name, lack of free memory, wrong/missing initial values of attributes. The return value of NewObject[A]() should always be checked in the code.

Object Destruction

The OM_DISPOSE() method is used to destroy an object. Unlike OM_NEW() the destructor may be invoked with DoMethod():

DoMethod(object, OM_DISPOSE);

The intuition.library has a wrapper for this however, named DisposeObject():

DisposeObject(object);

MUI Extensions to BOOPSI

The Magic User Interface not only builds on BOOPSI but also extends it. Other than providing a broad set of classes, MUI also modifies the BOOPSI mode of operation a bit. Two modifications are discussed in this chapter: extension of the IClass structure and MUI's own functions for object construction and destruction.

MUI uses the MUI_CustomClass structure for its internal class representation. This structure contains the standard Class structure inside. It is important when creating objects from MUI private classes with NewObject(), that the Class structure must be extracted from the MUI_CustomClass structure:

struct MUI_CustomClass *priv_class;
Object *obj;

obj = NewObject(priv_class->mcc_Class, NULL, /* ... */ TAG_END);

MUI's second modification of BOOPSI is using its own functions for object construction and destruction, MUI_NewObject[A]() and MUI_DisposeObject() respectively. These two functions are used only for objects of MUI shared (public) classes. Objects of private classes are created with NewObject() as shown above. The main advantage of MUI_NewObject() is automatic opening and closing of disk based shared classes. Here is an example:

Object *text;

text = MUI_NewObject(MUIC_Text, MUIA_Text_Contents, "foobar", TAG_END);

'MUIC_Text is a macro defined in <libraries/mui.h> and it expands to "Text.mui" string. All MUI public classes should be referenced by their MUIC_ macros rather than by direct string literals. It helps to detect mistyped class names, as a typo in a macro will be detected during compilation. The MUI checks if a class named Text.mui has been added to the public list of classes. If not, the class is found on disk, opened and used for creating the requested object. Closing the class when no longer in use is handled automatically too. All MUI objects should be disposed using MUI_DisposeObject(), which takes the object to be disposed as its only argument, the same as DisposeObject().

MUI_DisposeObject(text);