feelin.library is the heart of the object system, it constains core support functions such as memory management, low-level strings manipulation, hashing, list management; object support functions to manage IDs, classes, objects and shared object; and support functions for FC_Area. The library can also be customized in several ways.

Memory

F_CreatePoolA() · Create a memory pool
F_DeletePool() · Delete a memory pool
F_New() · Allocate memory
F_NewP() · Allocate memory from a pool
F_Dispose() · Deallocate memory

F_OPool() · Gain exclusive access to a pool
F_RPool() · Make pool available to others
F_SPool() · Gain shared access to a pool

Lists

F_LinkHead() · Insert node at the head of a FList
F_LinkInsert() · Insert a node into a FList
F_LinkMember() · Check if node is linked to a FList
F_LinkMove() · Move a node within or outside a FList
F_LinkRemove() · Remove a node from a FList
F_LinkTail() · Append node to tail of a FList
F_NextNode() · Iterate through the nodes on a FList

Strings

F_StrFmtA() · Format a string in a buffer
F_StrNewA() · Create a formated string
F_StrNewPA() · Create a formated string from a pool
F_StrLen() · Compute the length of a string
F_StrCmp() · Case sensitive string comparison

Debugging

F_LogA() · Logs debug information
F_AlertA() · Pops an alert request

Hashing

F_HashCreate() · Create a FHashTable
F_HashDelete() · Delete a FHashTable
F_HashFind() · Find an entry in a FHashTable
F_HashAddLink() · Add an entry to a FHashTable
F_HashRemLink() · Remove an entry from a FHashTable
F_HashAdd() · Add an entry to a FHashTable
F_HashRem() · Remove an entry from a FHashTable

Dynamic IDs

F_DynamicFindAttribute() · Find an attribute
F_DynamicFindMethod() · Find a method
F_DynamicFindID() · Find the Dynamic ID of a Method or an Attribute
F_DynamicResolveTable() · Resolve a table of Dynamic IDs
F_DynamicAddAutoTable() · Add a Dynamic auto table
F_DynamicRemAutoTable() · Remove a Dynamic auto table
F_DynamicNTI() · Dynamic version of NextTagItem()
F_DynamicFTI() · Dynamic version of FindTagItem()
F_DynamicGTD() · Dynamic version of GetTagData()

Object-oriented support

F_FindClass() · Find a class
F_OpenClass() · Gain access to a class
F_CloseClass() · Conclude access to a class
F_CreateClassA() · Create a public / private class
F_DeleteClass() · Make a class unavailable

F_DoA() · Perform method on object
F_ClassDoA() · Direct class call
F_SuperDoA() · Perform method on object coerced to superclass

F_NewObjA() · Create an object from a class
F_MakeObjA() · Create an object from the builtin object collection
F_DisposeObj() · Delete a Feelin object

Extensions

F_Set() · Specify attribute value for an object
F_Get() · Return attribute value of an object
F_Draw() · Redraw object
F_Erase() · Erase region with object background
F_Layout() · Modify object box

TYPES

FNode
FList
FHashLink
FHashTable

F_ClassDoA -- Direct class call

uint32 F_ClassDoA(FClass *Class, FObject Obj, uint32 Method, APTR Msg);
uint32 F_ClassDo(FClass *Class, FObject Obj, uint32 Method, ...);

Function

Invokes the supplied method on the specified object, as though it were the specified class.

Inputs

Class (FClass *)

FClass pointer to receive the message. The pointer may be NULL, in which case the function has no effect.

Obj (FObject)

An object. The method is performed even if the pointer is NULL.

Method (uint32)

Method to perform.

Msg (APTR)

Message associated with the Method.

Result

Class and method specific result.

See also

F_CloseClass -- Conclude access to a class.

void F_CloseClass(FClass *Class);

Function

This function informs the system that acces to a given class has been conclued. The user must not reference the class after this close. If the class is no longer used (user counter equals to zero) and the class has been loaded from disk by Feelin, the class will be removed from the system. Otherwise, if the class is a custom one, e.g. created with F_CreateClassA(), it must be removed by hand using the F_DeleteClass() function.

Inputs

Pointer to a FClass. This pointer may be NULL, in which case the function has no effect.

Result

Always NULL.

See also

F_CreateClassA -- Create a public / private class

FClass *F_CreateClassA(STRPTR Name, struct TagItem *);
FClass *F_CreateClass(STRPTR Name, ...);

Function

This function is for class implementors only, it's used to create a class.

You dispose a class created by this function with the F_DeleteClass() function.

Inputs

Name (STRPTR)

You can create public as well as private classes using this function. To create a private class just set Name to NULL.

Result

A pointer to a FClass or NULL to indicate an error.

Note

Classes are actually instances of the Class class. You should read its documentation for a summary of the available attributes and methods.

See also

F_CreatePoolA -- Create a memory pool (03.00)

APTR F_CreatePoolA(uint32 ItemSize, struct TagItem *TAGS);
APTR F_CreatePool(uint32 ItemSize, ...);

Function

Allocate and prepare a new memory pool. Each pool is a separate tracking system for memory of a specific type. Any number of pools may exist in the system.

Pools automatically expand and shrink based on demand. Fixed sized puddles are allocated by the pool manager when more total memory is needed. Many small allocations can fit in a single puddle. Allocations larger than the item size are allocated in their own puddles. At any time individual allocations may be freed. Or, the entire pool may be removed in a single step.

Inputs

Size of your biggest item.

Tags

FA_Pool_Attributes
Memory flags specifier, as taken by AllocMem(). Default is MEMF_CLEAR.

FA_Pool_ItemSize
Size of your biggest item.

FA_Pool_Items
Number of item that should fit in the same puddle. Default is 10.

FA_Pool_Name
The name of the memory pool (name of its semaphore actually). Only useful if you want to check your memory usage with the F_Allocs tool, or if you want to make some memory dump with the F_Dump tool.

FA_Pool_Public
If you set this attribute to TRUE, the pool semaphore is made public. This requires the FA_Pool_Name attribute to be defined as well.

Result

The address of a new pool header, or NULL for error.

Note

Feelin uses its very own memory management and tracking system. Thus, Feelin pools are not compatible with Exec ones.

A message of level FV_LOG_DEV is logged if an unknown attribute is found in the TAGS. This is only useful for people who, like me, forget to terminate their TAGS with the famous TAG_DONE.

See also

F_DeletePool() · F_NewP() · F_OPool() · Memory management

F_DeleteClass -- Make a class unavailable

F_DeleteClass(Class)
              A0
void F_DeleteClass(FClass *);

Function

Make a Feelin class unavailable for public consumption. Note that you must not delete classes with outstanding objects or sub classes.

Inputs

A pointer to a FClass created by F_CreateClassA(). This pointer may by NULL, in which case the function has no effect.

See also

F_CreateClassA() · F_CloseClass() · Class Handling

F_DeletePool -- Delete a memory pool (03.00)

F_DeletePool(Pool)
             A0
void F_DeletePool(APTR);

Function

Frees all memory in all puddles of the specified pool header, then deletes the pool header. Individual free calls are not needed.

Inputs

A memory pool, as returned by F_CreatePoolA().

See also

Memory management

F_Dispose -- Deallocate memory

F_Dispose(Mem)
          A1
void F_Dispose(APTR);

Function

Deallocates memory allocated using F_New() or F_NewP(). Only memory allocated by these functions may be freed with this function !

Inputs

Pointer to memory allocated by F_New() or F_NewP(). The pointer may be NULL, in which case this function has no effect. The function will never dispose a memory block that does not exists. Feelin memory system is absolutely safe.

Result

Always NULL.

Note

Memory freed is filled with 0xABADF00D. This may be useful :-) If you try to dispose a memory block that do not exists, a message is logged with level FV_LOG_CORE:

[myapp] Area{102C517C}.Dispose()> F_Dispose() Unknown Chunk 0x0000000D

See also

Memory management

F_DisposeObj -- Delete a Feelin object

F_DisposeObj(Obj)
             A0
void F_DisposeObj(FObject);

Function

Deletes an object and all of its auxiliary data. Objects are all created using F_NewObjA() or F_MakeObjA(). Objects of certain classes own other ones, which will also be deleted when the object is passed to F_DisposeObj(). Read the per-class documentation carefully to be aware of these instances.

Inputs

A FObject returned by F_NewObjA() or F_MakeObjA(). The pointer may be NULL, in which case this function has no effect.

Result

Always NULL.

Note

This function invokes the Dispose method, but also free object's class and perform some private job. Never send the Dispose method to dispose an object, this method can only be send to the super class within a custom class.

See also

Object Handling

F_DoA -- Perform method on object

F_DoA(Obj,Method,Msg)
      A0  D0     A1
uint32 F_DoA(FObject,uint32,APTR); uint32 F_Do(FObject,uint32,...);

Function

Invokes the supplied method on the specified object with the supplied arguments. The method is invoked on the object's true class.

Inputs

Obj (FObject)

An object. This pointer may be NULL, in which case the function has no effect.

Method (uint32 | STRPTR)

The method to invoke on the object. Since v08.10 you can also use a Dynamic ID such as "FM_Area_Setup", which is automatically resolved.

Msg (APTR)

The message associated with the method.

Result

Specific to the method and the object's class.

See also

F_ClassDoA() · F_SuperDoA() · Object Handling

F_Draw -- Draw an object

F_Draw(Obj,Flags)
       A0  D0
void F_Draw(FObject,uint32);

Function

This function is used by objects to (re)draw themselves, e.g. when some internal attributes were changed.

Most objects graphical representation in a window depends on some attributes. A gauge for example would depends on its Value attribute. Whenever someone changes such an attribute with a F_Set() call, the corresponding object receives the Set method with the new value. Rendering within the Set method can be dangerous as when receiving this method rastport to draw in may be NULL or even the Render object may not been created yet... That's why Feelin offers the F_Draw() function call.

First of all object's structure is examined to see if FRender is ready, RastPort not NULL, and object's flags ok (because an object may as well be hidden). The only time your object is allowed to render it's when it receives the Draw method. Drawing within other method is illegal and may be dangerous.

Inputs

Obj (FObject)

An object, subclass of the Area class. This pointer may be NULL, in which case the function has no effect.

Flags (uint32)

FF_Draw_Object or FF_Draw_Update. The flags given here affects the objects flags when Feelin calls the Draw method. There are several caveats when implementing Draw, see the developer documentation for details.

F_DynamicAddAutoTable -- Add a Dynamic auto table (06.00)

F_DynamicAddAutoTable(Table)
                      A0
BOOL F_DynamicAddAutoTable(FDynamicEntry *);

Function

This function, like F_DynamicResolveTable(), is used to resolve an array of Dynamic entries. F_DynamicResolveTable() is very useful when you need to resolve an array of already defined Dynamic IDs (e.g. some of your super class may be), but become difficult to use to obtain Dynamic IDs of objects that you may create or not. Here enters F_DynamicAddAutoTable().

F_DynamicAddAutoTable() handles everything automatically for you. The Dynamic entries of the array are linked in special buffers and are resolved on the fly when classes actualy define one of the Dynamic ID you have requested.

Example

STATIC F_RESOLES_ARRAY =
{
    F_RESOLVES_ADD("FA_Image_State"),
    F_RESOLVES_ADD("FM_Image_Draw"),
    F_RESOLVES_ADD("FM_Paint_Copy"),
F_ARRAY_END };
F_DynamicAddAutoTable(F_RESOLVES_PTR);

Dynamic IDs of the table may already been resolved, maybe classes we request IDs are already available, but we don't care of it right now.

if (FF_MyProg_UseImage & LOD->Flags)
{
    LOD->Image = F_NewObjA(FC_Image,Tags);
}

If the flag FF_MyProg_UseImage is set an Image object has been created (if everything ok). From here "FA_Image_State" and "FM_Image_Draw" are resolved and may be used as you wish. Auto resolve tables are resolved when classes are created, this is transparent for the user of the table, but very handy as you don't have tocare about anything.

Inputs

A Pointer to a static array of FDynamicEntry. The array must remains valid until you remove the table using the function F_DynamicRemAutoTable() otherwise auto resolve entries remains active and resolved IDs will be saved in the old space of Entry->ID.

Result

Returns TRUE if all buffers have been allocated correctly to handle automatic resolving. Otherwise the function destroys created entries and returns FALSE.

Note

Unlike F_DynamicResolveTable() this function uses some memory to handle the automatic resolving of your IDs and more CPU time (not that much in fact :-). Using automatic resolving is not always the best choice particuliarly if you only need Dynamic IDs defined by one of your super class.

See also

F_DynamicFindID()

F_DynamicFindAttribute

Not documented yet.

F_DynamicFindID -- Find the Dynamic ID of a Method or Attribute (06.00)

F_DynamicFindID(Name)
                A0
uint32 F_DynamicFindID(STRPTR);

Function

This function finds the Dynamic ID of a method or attribute.

Inputs

The name of the method or attribute to find. Remember naming conventions: "FM_<classname>_<methodname>" for methods and "FA_<classname>_<attributename>" for attributes.

Result

The Dynamic ID of the method or attribute.

See also

F_DynamicAddAutoTable() · F_DynamicResolveTable()

F_DynamicFindMethod

Not documented yet.

F_DynamicFTI -- Dynamic version of NextTagItem() (06.00)

F_DynamicFTI(TagValue,Tags)
             D0       A0
struct TagItem *Tag = F_DynamicFTI(uint32, struct TagItem *);

Function

Scans a tag list using F_DynamicNTI() and returns a pointer to the first item with ti_Tag matching the TagValue. Dynamic IDs are resolved on the fly.

Inputs

TagValue (uint32 | STRPTR)

Tag value to search for.

Tags (struct TagItem *)

Tag item list to search, may be NULL in which case the function has no effect.

Result

A pointer to the item with ti_Tag matching TagValue or NULL if no match was found.

See also

F_DynamicGTD()

F_DynamicGTD -- Dynamic version of GetTagData() (06.00)

F_DynamicGTD(TagValue,DefValue,TagList)
             D0       D1       A0
uint32 F_DynamicGTD(uint32,uint32,struct TagItem *);

Function

Searches a tag list for a matching tag, and returns the corresponding ti_Data value for the TagItem found. If no match is found, this function returns the value passed in as default. Dynamic IDs are resolved on the fly.

Inputs

TagValue (uint32)

Tag value to search for. This may be a string (Dynamic ID) it is resolved on the fly.

DefValue (uint32)

Value to be returned if TagValue is not found.

TagList (struct TagItem *)

Tag item list to search (may be NULL). Each Dynamic ID found in the list is resolved on the fly.

Result

The ti_Data value for the first matching TagItem or DefValue if a ti_Tag matching TagValue is not found.

See also

F_DynamicFTI() · F_DynamicNTI()


F_DynamicNTI -- Dynamic version of NextTagItem (06.00)

F_DynamicNTI(TagListPtr,TagItemPtr,Class)
             A0         A1         A2
struct TagItem * F_DynamicNTI(struct TagItem **, struct TagItem **, FClass *);

Function

Iterates through a tag list, skipping and chaining as dictated by system tags. TAG_SKIP will cause it to skip the entry and a number of following tags as specified in ti_Data. TAG_IGNORE ignores that single entry, and TAG_MORE has a pointer to another array of tags (and terminates the current array!). TAG_DONE also terminates the current array. Each call returns either the next tagitem you should examine, or NULL when the end of the list has been reached.

This function returns a pointer to the real tag item in the list but also resolve the Dynamic ID (if ti_Tag is a Dynamic ID) and save the results in TagItemPtr : the resolved Dynamic ID in ti_Tag and the corresponding data in ti_Data. Moreover, if a resolved ti_Tag is within the Dynamic space of the Class (e.g. an attribute defined by the class) the Dynamic ID of the class will be substracted to the Dynamic ID of ti_Tag. Thus if "FA_MyClass_Width" is the first attribute defined by the class ti_Tag will be set to '0'. If Class is NULL the resolved value is left untouched.

Example

enum    {
FA_MyClass_Width, FA_MyClass_Height, FA_MyClass_Light
};
...
F_METHOD(void,My_Set) { struct LocalObjectData *LOD = F_LOD(Class,Obj); struct TagItem *Tags = Msg, item;
while (F_DynamicNTI(&Tags,&item,Class)) switch (item.ti_Tag) {

if Class is not NULL and ti_Tag within the Dynamic range of the class the Dynamic ID of the class is substracted the the ID of ti_Tag.

        case FA_MyClass_Width:      LOD->Width  = item.ti_Data; break;
        case FA_MyClass_Height:     LOD->Height = item.ti_Data; break;
        case FA_MyClass_Light:      LOD->Light  = item.ti_Data; break;

if ti_Tag is not within the Dynamic range of the class ti_Tag is still resolved but saved as is.

        case FA_Pen_Shine:          LOD->Shine = (STRPTR) item.ti_Data; break;
        case FA_Pen_Dark:           LOD->Dark  = (STRPTR) item.ti_Data; break;
    }
}

Inputs

TagListPtr (struct TagItem **)

Doubly-indirect reference. The pointer is changed to keep track of the iteration.

TagItemPtr (struct TagItem **)

Doubly-indirect reference. ti_Tag and ti_Data of the current TagItem are saved in this array. If ti_Tag is a Dynamic ID it will be resolved and saved. More over, if Class is not NULL and the resolved ID of ti_Tag is within the Dynamic space of the class ti_Tag will be made relative to the Dynamic ID of the class. Thus, if ti_Tag is the first attribute defined by the class, 0 is saved in TagItem.ti_Tag.

Class (FClass *)

Used to make ti_Tag relative to the class. If Class is NULL ti_Tag is still resolved but saved as is.

Result

Returns a pointer to the next tag item until there is no more entry in the tag list. You should not use the returning value, but only check against NULL. You MUST use this pointer if you want to modify the contents of the item e.g. ti_Tag = TAG_IGNORE...

See also

F_DynamicFTI() · F_DynamicGTD()


F_DynamicRemAutoTable -- Remove a Dynamic auto table (06.00)

F_DynamicRemAutoTable(Table)
                      A0
void F_DynamicRemAutoTable(FDynamicEntry *);

Function

Use this function to remove dynamic tables added with F_DynamicAddAutoTable().

It is not dangerous to try to remove a table that was not added, as nothing will happen, but it is dangerous to leave auto tables active if you free the table, because resolved Dynamic IDs are saved in the space previously used by the table. In other words, resolved Dynamic IDs will be saved anywhere, and for sure this is not a good thing.

Inputs

A pointer to a NULL-terminated array of FDynamicEntry, the array added with F_DynamicAddAutoTable().


F_DynamicResolveTable -- Resolve an array of Dynamic IDs (06.00)

F_DynamicResolveTable(psResolve)
                      A0
void F_DynamicResolveTable(FDynamicEntry *);

Function

Use this function to resolve an array of Dynamic IDs.

Example

enum {  FM_Area_Setup,
        FM_Area_Cleanup,
        FA_Area_Height,
        FA_Area_Width       };
static FDynamicEntry Resolve[] = { "FM_Area_Setup", 0, "FM_Area_Cleanup", 0, "FA_Area_Height", 0, "FA_Area_Width", 0, NULL };
F_DynamicResolveTable(Resolve);
F_Log("FC_Area:\n" \ "Methods: Setup 0x%08lx - Cleanup 0x%08lx\n" \ "Attributes: Height 0x%08lx - Width 0x%08lx\n", F_ID(Resolve,FM_Area_Setup), F_ID(Resolve,FM_Area_Cleanup), F_ID(Resolve,FA_Area_Height), F_ID(Resolve,FA_Area_Width));

Inputs

Pointer to a NULL-terminated array of FDynamicEntry.

Result

The table resolved.

Result

This function uses no extra memory nor special or private structures. Dynamic IDs to resolve must already been defined. If a Dynamic ID is not already defined the fonction will print an error message to the debug console and the ID will be set to 0xFFFFFFFF (-1).

This function is simple but very useful when you need to resolve Dynamic ID defined by one of your super class as there will be no surprise. If you need some Dynamic IDs that may be defined or not (e.g. if you create object depeding on certain conditions) you should have a look to F_DynamicAddAutoTable(), the function uses memory and extra things, but is more powerful.

See also

F_DynamicFindID()


F_Erase -- Erase region with object's background

F_Erase(Obj,x1,y1,x2,y2,Flags)
        A0  D0 D1 D2 D3 D4
void F_Erase(FObject,uint16,uint16,uint16,uint16,uint32);

Function

This function is a simple interface to the Erase method.


F_FindClass -- Find a given Feelin class

F_FindClass(Name)
            A0
FClass * F_FindClass(STRPTR);

Function

This function searches the classes list for a class with the given name. The first class matching the name will be returned. Arbitration of the class list is done with semaphores.

Inputs

Name of the class to find.

Result

A pointer to a FClass, or NULL if not found.

See also

Class Handling


F_Get -- Return attribute's value of an object

F_Get(Obj,Attribute)
      A0  D1
uint32 F_Get(FObject,uint32);

Function

Returns from the specified object the value of the specified attribute. This function only gets the value of one attribute. Use the Get method to get several at a time.

Not all attributes will respond to this function. Those that will are documented on a class-by-class basis.

Inputs

Obj (FObject)

An object. This pointer may be NULL, in which case the function has no effect.

Attribute (uint32)

Attribute you want to know the value.

Result

Returns attribute value.

Example

val = F_Get(gauge,FA_Numeric_Value;

is the same as :

F_Do(gauge,FM_Get,
           FA_Numeric_Value, &val, TAG_DONE);

with this form you can get more:

F_Do(gauge,FM_Get,
           "FA_Numeric_Value", &val,
           "FA_Numeric_Max",   &max,
           "FA_Numeric_Min",   &min, TAG_DONE);

See also

F_Set()

F_Layout -- Modify object box

F_Layout(Obj,x, y, w, h, Flags)
         A0  D0 D1 D2 D3 D4
void F_Layout(FObject,int16,int16,uint16,uint16,uint32);

Function

Modifies object's box and invokes the specified object with the Layout method.

Inputs

Obj (FObject)

Object which box will be modified.

x, y, w, h (int16,int16,uint16,uint16)

New coordinates and dimensions.

Flags (bits32)

Not used yet, should be 0.

Result

Not defined yet.

See also

F_Draw()

F_LinkHead -- Insert node at the head of a FList

F_LinkHead(List,Node)
           A0   A1
FNode * F_LinkHead(FList *, FNode *);

Function

Add a FNode to the head of a doubly linked FList.

WARNING

This function does not arbitrate for access to the list. The calling task must be the owner of the involved list.

Inputs

List (FList *)

A pointer to the target FList.

Node (FNode *)

The FNode to insert at head.

Note

There is no security check on nodes added or removed. You should use the function F_LinkMember() if your are not always sure of what you do.

See also

F_LinkInsert()· F_LinkMove() · F_LinkRemove() · F_LinkTail()

F_LinkInsert -- Insert a node into a FList

F_LinkInsert(List,Node,Prev)
             A0   A1   A2
FNode *F_LinkInsert(FList *, FNode *, FNode *);

Function

Insert a FNode into a doubly linked list after a given FNode position. Insertion at the head of a list is possible by passing a zero value for Prev, although the F_LinkHead() function is slightly faster for that special case.

WARNING

This function does not arbitrate for access to the list. The calling task must be the owner of the involved list.

Inputs

List (FList *)

A pointer to the target FList.

Node (FNode *)

The FNode to insert after Prev.

Prev (FNode *)

The FNode after which to insert.

Note

There is no security check on nodes added or removed. You should use the function F_LinkMember() if your are not always sure of what you do.

See also

F_LinkHead() · F_LinkMove() · F_LinkRemove() · F_LinkTail() ·

F_LinkMember -- Check if node is linked to a FList

F_LinkMember(List,Node)
             A0   A1
BOOL F_LinkMember(FList *, FNode *);

Function

Returns TRUE if a given FNode is already linked to a FList.

WARNING

This function does not arbitrate for access to the list. The calling task must be the owner of the involved list.

Inputs

List (FList *)

Pointer to the target FList.

Node (FNode *)

The FNode to check.

See also

F_LinkHead() · F_LinkInsert() · F_LinkMove() · F_LinkRemove() · F_LinkTail()

F_LinkMove -- Move a node within or outside a FList

F_LinkMove(List,Node,Prev)
           A0   A1   A2
FNode * F_LinkMove(FList *,FNode *,FNode *);

Function

This function is equal to F_LinkRemove(List,Node) & F_LinkInsert(List,Node,Prev). This way you can easily move node inside a list or remove it from one and link it to another.

WARNING

This function does not arbitrate for access to the list. The calling task must be the owner of the involved list.

Inputs

List (FList *)

Pointer to the target FList.

Node (FNode *)

The FNode to move after Prev.

Prev (FNode *)

The FNode after which to insert.

Note

There is no security check on nodes added or removed. You should use the function F_LinkMember() if your are not always sure of what you do.

See also

F_LinkHead() · F_LinkInsert() · F_LinkRemove() · F_LinkTail()

F_LinkRemove -- Remove a node from a FList

F_LinkRemove(List,Node)
             A0   A1
void F_LinkRemove(FList *, FNode *);

Function

This function will remove a node from a Feelin list taking care that the node is a member of the list.

WARNING

This function does not arbitrate for access to the list. The calling task must be the owner of the involved list.

Inputs

List (FList *)

Pointer to the target FList.

Node (FNode *)

The FNode to remove.

Note

There is no security check on nodes added or removed. You should use the function F_LinkMember() if your are not always sure of what you do.

See also

F_LinkHead() · F_LinkInsert() · F_LinkMove() · F_LinkTail()

F_LinkTail -- Append node to tail of a FList

F_LinkTail(List,Node)
           A0   A1
FNode *F_LinkTail(FList*, FNode*);

Function

Add a node to the tail of a doubly linked list.

WARNING

This function does not arbitrate for access to the list. The calling task must be the owner of the involved list.

Inputs

List (FList *)

Pointer to the target FList.

Node (FNode *)

The FNode to insert at tail.

Note

There is no security check on nodes added or removed. You should use the function F_LinkMember() if your are not always sure of what you do.

See also

F_LinkHead() · F_LinkInsert() · F_LinkMove() · F_LinkRemove()

F_LogA -- Put debug information (05.00)

F_LogA(Level,Fmt,Params)
       D0    A0  A1
void F_LogA(uint32,STRPTR,int32 *); void F_Log(uint32,STRPTR,...);

Function

Writes the formated strings and values to the debug output, with a special debug level.

Since Feelin traces invokations, the function uses traces to add some useful information such as the class, the object and the method where the log occurs, then it prints your formated string and adds a line feed (\n):

F_Log(FV_LOG_DEV,"a bug ??")

produces the following log:

[myapp] Text{101EA608} @ Area.Connect() a bug ??

The debug output can be customized using the system variable LIB_CONSOLE.

Inputs

Level (uint32)

Level of the debug information. If this level is greater than the one chosen trought the system variable LIB_DEBUG no message is put to the debug output. Currently the following levels are defined :

FV_LOG_USER
This error level should only be used for major errors e.g. application cannot be created, window cannot be opened... The goal of this error level is to give information on errors that may confuse the user (not the developer).

FV_LOG_DEV
This error level is for people writting custom classes. It is generaly used by external classes. This error level should be used to notice the developer of a mistake e.g. a member of a family has been removed twice...

FV_LOG_CLASS
This error level is for feelin class management : class creation and handle, dynamic system, object creation and handle...

FV_LOG_CORE
A very low-level error only used for memory troubles (e.g. disposing a block that does no exists), hash link errors (e.g. removing a non linked node),...

Fmt (STRPTR)

exec.library RawDoFmt() style formatting string.

Params (int32 *)

Pointer to an array of formatting values.

Note

If the debug console cannot be used (because only processes can use dos.library, not tasks), an intuition requester is opened with the message as body, and the location of the error as title.

See also

F_AlertA()

F_MakeObjA -- Create an object from the builtin object collection

F_MakeObjA(Type,Params)
           D0   A0
FObject F_MakeObjA(uint32,uint32 *); FObject F_MakeObj(uint32,...);

Function

As you may have seen, there is no standalone class to create buttons or checkboxes. A button is a FC_Text object with special attributes (font, frame, back, scheme) and a "Release" input mode. A checkbox is a FC_Image object with special attributes and a "$checkbox-image" image spec.

One cas use macros to create those kind of objects, but this practice often result in big programs. Hopefuly, Feelin contains an object collection with several often used objects built in.

F_MakeObjA() takes the type of the object as first parameter, a list of additionnal (type specific) parameters, and a taglist (this helps to complete description of the object). Note that the additionnal parameters are not a taglist ! Note as well that the taglist comes right after the last parameter !!

The following objects can be created :

HLabel(STRPTR Label)
VLabel(STRPTR Label)
Button(STRPTR Label)
Bar
BarTitle(STRPTR Label)
Gauge(int32 Horiz, int32 Min, int32 Max, int32 Value)
Slider(int32 Horiz, int32 Entries, int32 Visible, int32 First)
String(STRPTR Label,uint32 Maxlen)
Checkbox(int32 Checked)

Example

obj = Button("Gofromiel");
obj = F_MakeObj(FV_MakeObj_Button,"Gofromiel",TAG_DONE); // same
obj = F_MakeObj(FV_MakeObj_Button,"Gofromiel",FA_Area_Font,"FP_Font_Big",TAG_DONE); // font

Inputs

Type (uint32)

Object type, one of FV_MakeObj_Xxx.

Params (uint32 *)

Type specific parameters. The optional taglist comes right after the last parameter. Thus, even if you don't supply your own attributes, you must en the list of parameters with TAG_DONE

Result

An object.

See also

F_DisposeObj() · F_NewObjA()

F_New -- Allocate memory

F_New(Size)
      D0
APTR = F_New(uint32)

Function

Allocate Size bytes of memory from feelin's default pool, and return a pointer. NULL is returned if the allocation failed.

Memory is allocated with MEMF_CLEAR flag. Use F_Dispose() to dispose memory allocated. Note that allocations are freed when feelin.library is removed from the system.

Inputs

The number of bytes to allocate.

Result

A pointer to the memory allocated, or NULL. The memory block returned is long word aligned.

Note

If the function fails to allocate memory, a message is logged with level FV_LOG_CORE:

F_New() Unable to allocate 400000008 bytes

See also

F_NewP() · F_Dispose() · Memory management

F_NewObjA -- Create an object from a class

F_NewObjA(Name,TAGS)
          A0   A1
FObject F_NewObjA(STRPTR, struct TagItem *); FObject F_NewObj(STRPTR, ...);

Function

This is the general method for creating objects from Feelin classes.

You specify a class by its name. If the class is not yet in memory or built into feelin.library, it will be loaded using OpenLibrary().

You further specify attributes for the object via a tagitem list, and they are applied to the resulting generic data object that is returned. Attributes are all defined and documented on a class-by-class basis.

This method not only invokes the New method for the class specified but make a lot of setup and security check. Never use the New method to create an object!

Inputs

Name (STRPTR)

The class name, e.g "Area". Classes names are case sensitive! You should better use macros like FC_Area instead of typing strings.

TAGS (struct TagItem *)

Pointer to an array of TagItems containing attributes/values pairs to be applied to the object being created. You can supply [I..] as [IS.] attributes.

Result

An object, which may be used in different contexts such as a gadget or image, and may be manipulated by generic functions. You eventually free the object using F_DisposeObj().

See also

F_CreateClassA() · F_DisposeObj() · Object Handling

F_NewP -- Allocate memory from a pool (03.00)

F_NewP(Pool,Size)
       A0   D0
APTR F_NewP(APTR,uint32);

Function

Allocate Size bytes from a memory Pool, and return a pointer. NULL is returned if the allocation fails.

Doing a F_DeletePool() on the pool will free all of the puddles and thus all of the allocations done with F_NewP() in that pool. (No need to F_DisposeP() or F_Dispose() each allocation).

Inputs

Pool (APTR)

A specific pool header, as returned by F_CreatePoolA().

Size (uint32)

The number of bytes to allocate.

Result

A pointer to a memory bock, or NULL if the allocation fails. The memory block returned is long word aligned.

Note

The pool function do not automatically protect an individual pool from multiple accesses. The reason is that in most cases the pools will be used by a single task. If your pool is going to be used by more than one task you must Semaphore protect the pool from having more than one task trying to allocate within the same pool at the same time. Each feelin pool has an embended semaphore for this purpose. Use this semaphore to access the pool from multiple task.

If the function fails to allocate memory, a message is logged with level FV_LOG_CORE.

See also

F_New() · Memory management

F_NextNode -- Iterate through the nodes on a FList

F_NextNode(Nodeptrptr)
           A0
FNode * F_NextNode(FNode *);

Function

Use this function to travel through a list of FNodes. Works even if you remove and dispose the returned list members in turn.

Inputs

Initially, you set a pointer variable to equal the Head field of the list. You pass the address of that pointer repeatedly to F_NextNode() until it returns NULL.

Result

Returns pointers to each node in the list in turn, and NULL when there are no more.

F_OpenClass -- Gain access to a Feelin class

F_OpenClass(Name)
            A0
FClass * F_OpenClass(STRPTR);

Function

This function returns a pointer to a FClass that was previously installed into the system. The class may exists in memory, or on disk; this is transparent to the F_OpenClass() caller.

If the class is not yet in memory, it will be loaded from "LIBS:Feelin/".

Inputs

Name of the class to open.

Result

A pointer to a FClass for a successful open.

See also

F_CloseClass() · Class Handling

F_OPool -- Gain access to a pool (03.00)

F_OPool(Pool)
        A0
void F_OPool(APTR);

Function

Feelin pools have an embended semaphore structure. This semaphore is not automatically locked when you allocate or deallocate memory from a pool, as the pool may or may not be public. It's up to the developer to use the semaphore or not depending on the pool usage.

Use this function to gain exclusive access to a pool.

Inputs

pointer to a memory pool as returned by F_CreatePoolA(). This pointer may be NULL in which case the function has no effect.

See also

F_RPool() · F_SPool() · Memory management

F_OPool -- Make pool available to others (03.00)

F_OPool(Pool)
        A0
void F_OPool(APTR);

Function

This function release a memory pool previously locked using F_OPool() or F_SPool().

Inputs

Pointer to a memory pool as returned by F_CreatePoolA(). This pointer may be NULL in which case the function has no effect.

See also

Memory management

F_Set -- Specify attribute value for an object

F_Set(Obj,Attribute,Value)
      A0  D1        D2
void F_Set(FObject,uint32,uint32);

Function

Specifies an attribute value.

This function invokes the Set method with only one tag/value pair.

Inputs

Obj (FObject)

An object. This pointer may be NULL, in which case the function has no effect.

Attribute (uint32)

Attribute to modify.

Value (uint32)

New value of the attribute.

See also

F_Get()

F_SPool -- Gain shared access to a pool (03.00)

F_SPool(Pool)
        A0
void F_SPool(APTR);

Function

Use this function to gain a shared access to a memory pool.

Inputs

pointer to a memory pool as returned by F_CreatePoolA(). This pointer may be NULL in which case the function has no effect.

See also

F_OPool() · F_RPool() · Memory management

F_StrCmp -- Case sensitive string comparison

F_StrCmp(String1,String2,Count)
         A0      A1      D1
int32 F_StrCmp(STRPTR,STRPTR,uint32);

Function

This function compares two strings, respecting cases. If the strings have differents lengths, the shorter is treated as if it were extended with zeros.

Inputs

String1, String2 (STRPTR)

Strings to be compared.

Count (uint32)

Number of characters to compare. The string comparison stops when a NULL-char (\0) is found.

Result

The relationship between String1 and String2 :

<0 means String1 < String2
=0 means String1 = String2
>0 means String1 > String2

Example

Note: ALL is defined within feelin.h and equals -1.

F_StrCmp("ABC","ABC",3)             >> 0
F_StrCmp("ABC","ABC",ALL)           >> 0
F_StrCmp("ABCd","ABC",3)            >> 0
F_StrCmp("ABc","ABC",ALL)           >> 32
F_StrCmp("ABCd","ABC",ALL)          >> 100

F_StrFmtA -- Format a string in a buffer

F_StrFmtA(Buffer,Fmt,Params);
          A0     A1  A2
void F_StrFmtA(STRPTR,STRPTR,int32 *); void F_StrFmt(STRPTR,STRPTR,...);

Function

This function is a simple interface to exec's RawDoFmt().

Inputs

Buffer (STRPTR)

The buffer in which the formated string will be written. You must be sure that there is enough space to write the string.

Fmt (STRPTR)

Format of the string.

Params (int32 *)

A stream of data that is interpreted according to the format of the string.

See also

F_StrNewA()

F_StrLen -- Computes the length of a string

F_StrLen(Str);
         A0
uint32 F_StrLen(STRPTR);

Function

Computes the length of a string

Inputs

A string.

Result

The length of the string.

F_StrNewA -- Allocate and format a string

F_StrNewA(LengthPtr,Fmt,Params);
          A0        A1  A2
STRPTR F_StrNewA(uint32 *,STRPTR,int32 *); STRPTR F_StrNew(uint32 *,STRPTR,...);

Function

This function allocate enough memory to hold a formated string. This function is very useful because it avoid buffer overflows as formated strings have always enough space to be written.

Inputs

LengthPtr (uint32 *)

If this parameter is not NULL, the length of the formated string is written in it.

Fmt (STRPTR)

Format of the string.

Params (int32 *)

A stream of data that is interpreted according to the format of the string.

Result

The result is a pointer to a formated string, or NULL if out of memory. This pointer can be diposed with the F_Dispose() function.

Example

uint32 len;
STRPTR str;
if (str = F_StrNew(&len,"File %s - Length %ld",file_name,file_size)) { Printf("str '%s' - lenght %ld",str,len);
F_Dispose(str); }

See also

F_StrFmtA()

F_SuperDoA -- Perform method on object coerced to superclass

F_SuperDoA(Class,Obj,Method,Msg)
           A2    A0  D0     A1
uint32 F_SuperDoA(FClass *,FObject,uint32,APTR); uint32 F_SuperDo(FClass *,FObject,uint32,...);

Function

This function invokes the supplied method on the specified object, as though it were the superclass of the supplied class.

Inputs

Class (FClass *)

A class, whose superclass is to receive the method. This pointer may be NULL as the superclass, in which case the function has no effect.

Obj (FObject)

An object.

Method (uint32)

Method to invoke.

Msg (APTR)

Message associated with the Method.

Result

Class and method-specific result.

See also

F_ClassDoA() · F_DoA() · Object Handling · Class Handling

FList -- (01.00)

typedef struct FeelinList
{
    struct FeelinNode              *Head;
    struct FeelinNode              *Tail;
}
FList;

Function

The anchor where FNodes are linked together.

Members

Pointers to the head (the fist element) and the tail (the last element) of the list. Head equals Tail, when there is only one FNode linked. Head and Tail equal NULL when the FList is empty.

FHashLink -- (06.00)

typedef struct FeelinHashLink
{
    struct FeelinHashLink          *Next;
    uint8                          *Key;
    uint32                          KeyLength;
    APTR                            Data;
}
FHashLink;

Function

This structure is used to store hashed entries in a FHashTable.

Members

Next (FHashLink *)

Next FHashLink with the same hash value.

Key (uint8 *)

Key used to store Data in the FHashTable.

KeyLength (uint32)

Length of the Key.

Data (APTR)

User data.

FHashTable -- (06.00)

typedef struct FeelinHashTable
{
   uint32                           Size;
   FHashLink                      **Entries;
}
FTable;

Function

This structure is created with the F_HashCreate() function.

Members

Size (uint32)

Size of the table e.g. the number of entries that can be stored directly in the array.

Entries (FHashLink **)

A pointer to an array of FHashLink pointers.

FNode -- (01.00)

typedef struct FeelinNode
{
    struct FeelinNode              *Next;
    struct FeelinNode              *Prev;
}
FNode;

Function

This structure is used for each element in a FList.

Members

The Next and Prev pointers are the links to the next and previous elements in the list.