General Rules and Purpose of Subclassing - Revision history

Krashan: Added link to Polish version.

2011-01-22T12:23:28Z

Added link to Polish version.

AusPPC: Fixing minor typos and other small changes for readability.

2011-01-06T21:52:59Z

Fixing minor typos and other small changes for readability.

Show changes

Krashan: Bugfix: instance data area size is limited to 64 kB.

2011-01-05T21:06:19Z

Bugfix: instance data area size is limited to 64 kB.

Krashan: Formatting.

2011-01-03T13:40:18Z

Formatting.

Krashan: Formatting.

2011-01-03T13:38:59Z

Formatting.

Krashan: Style.

2010-12-31T08:58:35Z

Style.

Krashan: Style.

2010-12-31T08:55:27Z

Style.

Krashan: Style.

2010-12-31T08:54:43Z

Style.

Krashan: Contents++.

2010-12-31T08:53:13Z

Contents++.

Krashan: Minor style changes.

2010-12-31T07:09:02Z

Minor style changes.

← Older revision		Revision as of 12:23, 22 January 2011
Line 1:		Line 1:
	''Grzegorz Kraszewski''		''Grzegorz Kraszewski''

		+	----
		+	<small>This article in other languages: [[Cele i zasady tworzenia klas pochodnych\|Polish]]</small>

	==Introduction==		==Introduction==

← Older revision		Revision as of 21:06, 5 January 2011
Line 15:		Line 15:
	Object data are stored in a memory area automatically allocated for every object created. The object data area is used for storing attribute values and for internal variables and buffers. This area is usually defined as a structure. Size of the area is passed to ''MUI_CreateCustomClass()'' function. In a class hierarchy, every class may add its own contribution to the object data area. Unlike in C++, a class has no direct access to anything except its own data area. It can't access data defined in the superclass (In C++ it is possible if a field is declared as ''protected'' or ''public''). Object data defined in any of superclasses may be only accessed using methods or attributes provided by these superclasses.		Object data are stored in a memory area automatically allocated for every object created. The object data area is used for storing attribute values and for internal variables and buffers. This area is usually defined as a structure. Size of the area is passed to ''MUI_CreateCustomClass()'' function. In a class hierarchy, every class may add its own contribution to the object data area. Unlike in C++, a class has no direct access to anything except its own data area. It can't access data defined in the superclass (In C++ it is possible if a field is declared as ''protected'' or ''public''). Object data defined in any of superclasses may be only accessed using methods or attributes provided by these superclasses.

−	~~There is no limit on object~~ data area ~~size, other than system memory available~~. The area data is always cleared to all zeros at object creation. If a clas does not need any object instance data it can pass 0 as the area size to ''MUI_CreateCustomClass()''.	+	Because of internal [[Short BOOPSI Overview\|BOOPSI]] design, the size of the data instance area is limited to 64 kB. Large buffers should be allocated dynamically in OM_NEW() and freed in OM_DISPOSE(). The area data is always cleared to all zeros at object creation. If a clas does not need any object instance data it can pass 0 as the area size to ''MUI_CreateCustomClass()''.

@@ Line 114: / Line 114: @@
 Some conditions must be fulfilled before calling this function.
 * Call it only when the class was really created. Calling it with ''NULL'' class pointer is deadly (hence the ''NULL'' check in the example).
-* Do not delete a class until it has any subclasses or objects. The best practice is to create all classes before creating the application GUI and to dispose them after the final MUI_DisposeObject() of the main ''Application'' object. Classes should be deleted in the reversed order of creation. ''MUI_DeleteCustomClass()'' returns a boolean value. It is FALSE when a class cannot be deleted because of orphaned subclasses or objects.
+* Do not delete a class until it has any subclasses or objects. The best practice is to create all classes before creating the application GUI and to dispose them after the final ''MUI_DisposeObject()'' of the main ''Application'' object. Classes should be deleted in the reversed order of creation. ''MUI_DeleteCustomClass()'' returns a boolean value. It is FALSE when a class cannot be deleted because of orphaned subclasses or objects.

← Older revision		Revision as of 13:38, 3 January 2011
Line 104:		Line 104:

	The last argument is an address of the data gate (''EmulLibEntry'' structure). Programmers experienced on M68k programming may notice that there is a difference – in M68k code just dispatcher function address has been used here. As mentioned above, seamless M68k code support requires that program execution passes through the data gate when going from system code to the dispatcher. That is why the data gate address is placed as this argument, then the data gate contains a real dispatcher address.		The last argument is an address of the data gate (''EmulLibEntry'' structure). Programmers experienced on M68k programming may notice that there is a difference – in M68k code just dispatcher function address has been used here. As mentioned above, seamless M68k code support requires that program execution passes through the data gate when going from system code to the dispatcher. That is why the data gate address is placed as this argument, then the data gate contains a real dispatcher address.
		+

	==Class Disposition==		==Class Disposition==

@@ Line 67: / Line 67: @@
     /* ... */
-Arguments of the dispatcher are the same as arguments of a method. They are passed in virtual M680x0 processor address registers A0, A1 and A2 instead of being just arguments. The dispatcher's data gate is passed as an argument to ''MUI_CreateCustomClass()''. The data gate is also used when native application calls a native dispatcher. It introduces some overhead, but a negligible one. Many programmers prefer to hide these details behind a set of preprocessor macros, such macros have been not used here however, for better understanding.
+Arguments of the dispatcher are the same as arguments of a method. They are passed in virtual M680x0 processor address registers A0, A1 and A2 instead of being just arguments. The dispatcher's data gate is passed as an argument to ''MUI_CreateCustomClass()''. The data gate is used even when native application calls a native dispatcher. It introduces some overhead, but a negligible one. Many programmers prefer to hide these details behind a set of preprocessor macros, such macros have been not used here however, for better understanding.
 The ''Msg'' type is a root type for all method messages. It defines a structure containing only the method identifier field (defined as ULONG). All following parameters have to keep the CPU stack align, as ''DoMethod()'' builds the message on the stack. It requires that every parameter is defined either as an ''IPTR'' or as a pointer.

@@ Line 53: / Line 53: @@
 A dispatcher function is a kind of jump table for methods. When any method is called on an object (with ''DoMethod()''), BOOPSI finds a dispatcher of the object's class and calls it. The dispatcher checks a method identifier, which is always the first field of any method message. Based on the identifier, a method is called. If a method is unknown to the class, the dispatcher should pass it to the superclass with ''DoSuperMethod()'' call.
-The dispatcher is a case of [[Hooks|hook]] function. It makes its calling convention independent on programming language. A disadvantage of this is that dispatcher's arguments are passed in virtual M68k processor registers. This inconvenience comes with support for legacy M68k software and allows for native PowerPC classes to be used by M680x0 applications and old M68k classes to be used by native applications. Being a hook, a dispatcher needs a ''EmulLibEntry'' structure to be created and filled first. The structure is defined in  ''<emul/emulinterface.h>'' and acts as a data gate between PowerPC native code and M68k emulator.
+The dispatcher is a case of [[Hooks|hook]] function. It makes its calling convention independent on programming language. A disadvantage of this is that dispatcher's arguments are passed in virtual M68k processor registers. This inconvenience comes with support for legacy M68k software and allows for native PowerPC classes to be used by M68k applications and old M68k classes to be used by native applications. Being a hook, a dispatcher needs a ''EmulLibEntry'' structure to be created and filled first. The structure is defined in  ''<emul/emulinterface.h>'' and acts as a data gate between PowerPC native code and M68k emulator.
   const struct EmulLibEntry ClassGate = {TRAP_LIB, 0, (void(*)(void))ClassDispatcher};

← Older revision		Revision as of 08:53, 31 December 2010
Line 85:		Line 85:
	}		}

−	For every method a message pointer is typecasted to a message structure of this particular method. Some programmers place the code of methods inside the ''switch'' statement directly, especially if methods are short and only a few.	+	For every method a message pointer is typecasted to a message structure of this particular method. Some programmers place the code of methods inside the ''switch'' statement directly, especially if methods are short and only a few. In the example above, some methods of ''Area'' class are overridden. The naming scheme of method functions is an example, there are no constraints on this. Prefixing method functions names with a class name has an advantage of avoiding name conflicts between custom classes if method functions are not declared as ''static''.
		+
		+
		+	==Class Creation==
		+
		+	Having all components done (methods, dispatcher, gate, object data structure) one can create a MUI class.
		+
		+	struct MUI_CustomClass *MyClass;
		+
		+	MyClass = MUI_CreateCustomClass(NULL, MUIC_Area, NULL, sizeof(struct MyClassData),
		+	(APTR)&MyClassGate);
		+
		+	The first argument is a library base if the created class is public. Writing MUI public classes will be covered later. Let's say for now, that public classes are implemented as shared libraries, so such a public class has a library base. For private classes this argument should be always ''NULL''.
		+
		+	The next two arguments are used alternatively and specify the superclass. The superclass may be either private (referenced by pointer) or public (referenced by name). Public classes are subclassed usually, so the pointer is set to ''NULL'' as in the example. More complex projects may use multilevel subclassing and subclass their own private classes. In this case, a pointer to a private class is passed as the first argument and the second one is ''NULL''.
		+
		+	The fourth argument defines size of the object data area in bytes. In most cases object data area is defined as a structure, so using ''sizeof()'' operator is the obvious way of determining the size. If the class does not need any per-object data, zero may be passed here.
		+
		+	The last argument is an address of the data gate (''EmulLibEntry'' structure). Programmers experienced on M68k programming may notice that there is a difference – in M68k code just dispatcher function address has been used here. As mentioned above, seamless M68k code support requires that program execution passes through the data gate when going from system code to the dispatcher. That is why the data gate address is placed as this argument, then the data gate contains a real dispatcher address.
		+
		+	==Class Disposition==
		+
		+	A MUI class is disposed with a call to ''MUI_DeleteCustomClass()''.
		+
		+	if (MyClass) MUI_DeleteCustomClass(MyClass);
		+
		+	Some conditions must be fulfilled before calling this function.
		+	* Call it only when the class was really created. Calling it with ''NULL'' class pointer is deadly (hence the ''NULL'' check in the example).
		+	* Do not delete a class until it has any subclasses or objects. The best practice is to create all classes before creating the application GUI and to dispose them after the final MUI_DisposeObject() of the main ''Application'' object. Classes should be deleted in the reversed order of creation. ''MUI_DeleteCustomClass()'' returns a boolean value. It is FALSE when a class cannot be deleted because of orphaned subclasses or objects.

@@ Line 35: / Line 35: @@
   IPTR SomeMethod(Class *cl, Object *obj)
+  {
-    struct ObjData *d = (struct ObjData*)INST_DATA(cl, obj);
+    struct ObjData *d = (struct ObjData*)'''INST_DATA(cl, obj)''';
     d->SomeVal = 14;
@@ Line 47: / Line 47: @@
   result = DoSuperMethod(cl, obj, ''MethodID'', ...);
-The second form rebuilds the method message from variable arguments, and is used when the message is modified before calling the superclass method. The super method may be called in any place of the method, or may be not called at all. For MUI standard classes and methods rules of calling super methods are described in the documentation and will be discussed later in this tutorial. For custom methods the question of calling a super method is up to the application programmer.
+The second form rebuilds the method message from variable arguments, and is used when the message is modified before calling the superclass method. The super method may be called in any place of the method, or may be not called at all. For MUI standard classes and methods, rules of calling super methods are described in the documentation and will be discussed later in this tutorial. For custom methods the question of calling a super method is up to the application programmer.
@@ Line 53: / Line 53: @@
 A dispatcher function is a kind of jump table for methods. When any method is called on an object (with ''DoMethod()''), BOOPSI finds a dispatcher of the object's class and calls it. The dispatcher checks a method identifier, which is always the first field of any method message. Based on the identifier, a method is called. If a method is unknown to the class, the dispatcher should pass it to the superclass with ''DoSuperMethod()'' call.
-The dispatcher is a case of [[Hooks|hook]] function. It makes its calling convention independent on programming language. A disadvantage of this is that dispatcher's arguments are passed in virtual M68k processor registers. This inconvenience comes with support for legacy M680x0 software and allows for native PowerPC classes to be used by M680x0 applications and old M68k classes to be used by native applications. Being a hook, a dispatcher needs a ''EmulLibEntry'' structure to be created and filled first. The structure is defined in  ''<emul/emulinterface.h>'' and acts as a data gate between PowerPC native code and M680x0 emulator.
+The dispatcher is a case of [[Hooks|hook]] function. It makes its calling convention independent on programming language. A disadvantage of this is that dispatcher's arguments are passed in virtual M680x0 processor registers. This inconvenience comes with support for legacy M680x0 software and allows for native PowerPC classes to be used by M680x0 applications and old M680x0 classes to be used by native applications. Being a hook, a dispatcher needs a ''EmulLibEntry'' structure to be created and filled first. The structure is defined in  ''<emul/emulinterface.h>'' and acts as a data gate between PowerPC native code and M680x0 emulator.
   const struct EmulLibEntry ClassGate = {TRAP_LIB, 0, (void(*)(void))ClassDispatcher};