====== PyMUI C Types ====== ===== Concepts and purpose ===== 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 [[http://www.python.org/doc/2.5.4/lib/module-ctypes.html|its documentation]] before. **Important:\\ Don't use ''ctypes'' types directly with PyMUI, they missing some important features and may cause bad results or crashes.** ===== Classes ===== **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. ==== Base mixin types ==== === PyMUICType === 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): ^ Name ^ Type ^ Usage ^ | **''x.%%__long__%%()''** | //method// | Return a ''long'' representation of ''x'' usable by MUI. | | **''x.FromLong(y)''** | //classmethod// | Return instance of the same type as ''x'' based on the ''y'' MUI integer value. | | ''x.value'' | //property// | Inherited from the base ''ctypes'' type (see its documentation).\\ May not exists for some ''ctypes'' like pointer, so the mixin implementation is used. Default is to return the result of ''long(x)''. | | ''x.ArrayOf(n)'' | //classmethod// | Return a new PyMUI type, to use for array of ''n'' value of the type of ''x''. | | ''x._PointerType()'' | //classmethod// | Return a new PyMUI type to use for pointers on the type of ''x''. | | ''x._PointerOn()'' | //property// | Return a new instance of ''x._PointerType()'', pointing on ''x''. | | ''x._iskept'' | //property// | Return ''True'' if an object needs to be tracked to not be deallocated else ''False''.| | ''x._keep()'' | //method// | Return the object to track (only use it if ''_iskept'' is ''True''). | - //''x'' denotes an instance of a PyMUI type.//\\ - //**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. === Base mixin classes === 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. == CSimpleValue == 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). == CComplexBase == 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. == CStructure == 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. == CPointer == 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. ==== Integers types ==== 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. ^ Name((Note as this names mimic C ones.)) ^ Meaning ^ | c_BYTE | 8bit signed integer | | c_UBYTE | 8bit unsigned integer | | c_WORD | 16bit signed integer | | c_UWORD | 16bit usigned integer | | c_LONG | 32bit signed integer | | c_ULONG | 32bit unsigned integer | ==== Specials types ==== Various specials PyMUI types. ^ Name ^ Meaning ^ | c_BOOL | Boolean value (''True=1'' or ''False=0''), based on ''c_ULONG''. | | c_CHAR | A single character. Acts like a ''CSimpleValue'' but based on ''PyMUICType''.\\ ''value'' returns a single character string object. | | c_FLOAT | A float (simple precision floating point) value. Subclass of ''CSimpleValue'' but ''%%__long__%%'' returns an integer value as if the 32bit buffer is encoded as a plain unsigned long. | | c_DOUBLE | Like ''c_FLOAT'' but for double precision floating point values. | | c_APTR | Non-typed pointer. Subclass of ''CSimpleValue'', so the only //pointer// not subclass of ''CPointer'' mixin.\\ The initial value can be any instance of a ''CPointer'' subclass, the pointer value will be the the one of the instance. | | c_TagItem | Structure with same fields as the C ''TagItem''. | | c_MinMax | Structure with same fields as the C ''MUI_MinMax''. | ==== Pointers types ==== All following types use the CPointer mixin. ^ Name ^ Meaning ^ | c_STRPTR | Like C ''STRPTR'' type, based on ''c_char_p'' ''ctypes'' type. For '''\0''' ended string only.\\ Implements ''%%__len__%%'' and ''%%__getitem__%%'' methods. | | c_pSTRPTR | Pointer on ''c_STRPTR''. Accepts ''list'' and ''tuple'' object of c_STRPTR or str objects as initial value (convert it in internal as an array).\\ Implements ''%%__iter__%%'' that give a iterator on pointed c_STRPTR instances, stop on the first NULL pointer. | | c_pFLOAT | Pointer on ''c_FLOAT''. | | c_pDOUBLE | Pointer on ''c_DOUBLE''. | | c_PyObject | Pointer on any Python object. | | c_BoopsiObject | Pointer on C ''Object'', as a generic BOOPSI object. | | c_MUIObject | Pointer on C ''Object'', as a MUI BOOPSI object. | | c_MenuitemTitle | Subclass of ''c_STRPTR'' with the special meaning to returns ''NM_BARLABEL'' constant than a str object if the ''%%__long__%%'' value returns this constant. | | c_ListTitle | Subclass of ''c_STRPTR'', but returns ''True'' if the pointer value is 1. | | c_pTagItem | Pointer on ''c_TagItem''. | | c_pTextFont | Subclass of ''c_APTR'' for now. | | c_pList | Subclass of ''c_APTR'' for now. | | c_pMinList | Subclass of ''c_APTR'' for now. | === Hooks types === 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 [[overload|the MCC overloading paradigm]]** ^ Name ^ Meaning ^ | c_Hook | The base type of all PyMUI hook types.\\ First argument value should be a callable accepting zero, one or two arguments dependings on the second argument ''argstypes'' of c_Hook.\\ This second argument shall be an iterable of two PyMUI types, ''None'' or ''long'':\\ If an item is ''None'', the corresponding C hook argument is not given to the callable.\\ If a ''long'' is used, the C value is given as a unsigned long.\\ If a PyMUI type is given, an instance of this type is created using ''FromLong'' classmethod. | | c_NotifyHook | Subclass of ''c_Hook'', used for ''Notify.CallHook'' method. | | c_List_ConstructHook | Subclass of ''c_Hook'', used as type of ''List.ConstructHook'' attribute. | | c_List_DestructHook | Subclass of ''c_Hook'', used as type of ''List.DestructHook'' attribute. | | c_List_DisplayHook | Subclass of ''c_Hook'', used as type of ''List.DisplayHook'' attribute. |