The AmigaOS has been developed for a 32bit architecture, and MUI is based on the AmigaOS BOOPSI paradigm. So the MUI API has the particularity to pass data using only 32bit integer values, unsigned or signed. When more data or floating point values are needed to be transfered between functions, a pointer (32bit integer) is used.

PyMUI uses Python paradigm, where object paradigm matters: on the C side there is only PyObject structure, that contains and know how to handle all the language object types.

To make the bridge between these two far worlds, PyMUI uses special classes with the ability to be convertible into 32bit integer values on the C side of the PyMUI module. This value is also available on the pure Python side as a long or int object because all these classes shall implement the __long__() method.
And for the other direction, PyMUI C types can also be created using an integer value comming from the MUI C world.

The core API of PyMUI uses these types when it needs to gives a Python object to MUI, so the user should be ready to play with instances of these classes in almost all PyMUI interfaces.

At first glance this can look weird, for example, you wait for an integer value from a MUI attribute and you get a c_ULONG instance object: it's not directly a plain integer Python object as you might have thought when you first start using PyMUI. You need to first convert this object into this plain integer object (could be a long or int) to use it as is.

This design gives the ability to handle a MUI C integer value in versatiles ways:

• as the integer itself (long(x) always return this MUI value, even if it hasn't an integer meaning).
• as a string or any other complex object.

This is really usefull for example with MUI attributes marked as waiting for a STRPTR but the given value may also be read as an integer value with a special meaning, like -1. If you try to use this value as a string pointer you will get some problems…
So we can't convert the integer value to a unique Python object directly, this step is let to GUI designer that should check himself the value before to convert it to a more complex Python object.

This example shows you something important with PyMUI: you are not protected against mistakes in bad value usage!
PyMUI lets you converting a -1 integer value into a str Python object if you want… imminent system failure follows!

Other important point about PyMUI types: all of them are subclasses of ctypes module types. PyMUI uses it to simplify declarations and usages of some complexes C types, like structures and arrays.
Strongly suggested to read its documentation before.

Important:
Don't use ctypes types directly with PyMUI, they missing some important features and may cause bad results or crashes.

The naming convention used for PyMUI types requires that types name starts by c_ characters.
Only the base type PyMUICType breaks this rule and you're strongly advised to use this convention.

A base class of all PyMUI types and mixin subclasses below.

This class is used as mixin classes, this means that it's not the first class in the inheriting tree of subclasses. The first class is always a type from the ctypes module or a PyMUICTypes subclasses.

But this base permits to check easily if an object is an instance of a PyMUI type or not just by using the Python code:

instance(obj, PyMUICType)

That shall returns True object if it's instance.

This mixin class adds methods and properties to ctypes types like the long() method to implement PyMUI concepts explained in the first chapter.

For all PyMUI types following class attributes are available (meaning may change depending on the type):

1. x denotes an instance of a PyMUI type.
   
2. Bold name attributes shall be implemented by subclasses (may be implemented by a mixin subclasses below).

Notes one value property:
ctypes uses a Read/Write value property. But PyMUI ones is ReadOnly if ctypes base type doesn't define one.

Notes about arrays:
You shall not use the ctypes array paradigm to create arrays. Always use ArrayOf method or the generated type is not a PyMUI type.

Notes about pointers:
Pointer types shall accepts as argument an instance of the pointed prototype or nothing.
If nothing is given, the pointer value is NULL.

They implements or overload some PyMUICType attributes. Notes that no mixin class exists for array. In fact a private class exists but you shall use the PyMUICType method ArrayOf() instead.

Base mixin class for all C simple integer types.

Defines __long__ and FromLong methods.
All C integers that can be stored in a 32bit integer use this mixin, they are all defined by PyMUI (see below).

Base mixin class for structure and array types.

Defines __long__ and FromLong methods. Set _iskept to True.
__long__ returns the address of the memory buffer that contains the structure or array.

Base mixin class that user shall use to defines stuctures types.

Based on Structure ctypes type and CComplexBase type.

Works as ctypes defines, so please read ctypes structure documentation.
_fields_ attribute shall be defined for each subclasses.

Base mixin class that user shall use to defines special pointer types.

To use a pointer on an existing PyMUI type is more simple to use the classmethod _PointerType(). But in some cases is required to implement/overload some attributes as do PyMUI with c_BoopsiObject type for example. In this cases use this mixin.

Defines __long__ and FromLong methods. Set _iskept to True.
__long__ returns the value of the pointer (so the address of the pointed memory buffer).

Note: if the result of _PointerType() is used as a base class, you need to defines the class attribute _type_ as the ctypes documentation on pointer types explains.

This is the list of all C integer types encountered in MUI development.

They are all subclasses of CSimpleValue mixin and all of them can be created by giving an int or long object as argument (zero - 0 by default) used as the value of the object.
This types restrict the range of possibles values like C versions do, so the input argument may be changed.

Various specials PyMUI types.

All following types use the CPointer mixin.

Hooks types are CPointer based but they have some specials attributes that may needs some details here.

Important:
Hook are bad to use and may cause bad design. So since MUI V4, they tends to disapear adn to be removed from MUI and MCC's. Try to not use it when possible, use the MCC overloading paradigm