SEAL Forum Index SEAL
The SEAL Forums
 
 FAQFAQ   SearchSearch   MemberlistMemberlist   UsergroupsUsergroups   RegisterRegister 
 ProfileProfile   Log in to check your private messagesLog in to check your private messages   Log inLog in 

sfcList Tutorial

 
Post new topic   Reply to topic    SEAL Forum Index -> Programming Related
View previous topic :: View next topic  
Author Message
ganesh



Joined: 11 Jul 2002
Posts: 133
Location: Vancouver, BC, CA

PostPosted: Tue Jul 30, 2002 2:31 pm    Post subject: sfcList Tutorial Reply with quote

Code:

sfcList Tutorial
================


by Ganesh Swami
ganesh_net AT hotmal DOT com


Topic Of Contents
================


0. Introduction
1. Structure
2. Functions
3. Profiler
4. ToDo
5. History

0. Introduction
================

sfcList is a small, lightweight and easy to use
"class" of functions written for SEAL.
   
It belongs to Seal Foundation Classes (sfc) and
hence the prefix.

sfcList is used extensively throughout SEAL 3.0 and is
very modular and bug free. It has been virtually torn
apart and studied for bugs. It must be the most stable
code of SEAL yet.

sfcList is written in C (for no overheads or whatever).


1. Structure
================

sfcList as a whole has two parts, namely sfcList and
sfcListItem. You can think of it as a ListView and a
ListViewItem or a TreeView and a TreeViewItem ( or a b*******
and a BullShitItem).

struct sfcList {
  sfcListItem *head;   
  sfcListItem *tail;   
  int   count;      
};

sfcList contains three fields, two pointers, one to the
head and one to the tail of the list. The third is the
number of items in the list. You do not (and should not)
modify any of these by hand.


struct sfcListItem {
  char   *name;      
  void   *data;
  sfcList *chain;     
  sfcListItem *next;
  sfcListItem *prev;
};

sfcListItem contains five fields, name, data, chain, next and prev.

name = Name of the item. Automatically deleted when list is destroyed. (One exception)
data = Pointer to the data the Item is going to hold. Automatically deleted ...(One exception)
chain = Pointer to the parent, or the sfcList which contains this Item.
next = Pointer to the next Item in the list.
prev = Pointer to the previous Item in the list.


Of these, you should not modify chain, next and prev. You have been warned !!

2. Functions
================

Now, here are the functions to work with the above data structures.

sfcList  *list_create();
Create a new list.

sfcList *myList = NULL;
myList = list_create();

---------------------------

sfcListItem *list_append(sfcList  *);
Append an item internally and return its address.

This is one of the two ways to add items to the list.

sfcListItem *myItem = NULL;
myItem = list_append (myList);

//myItem is in every way the last node of the list "myList".

You can now store anything in this Item. Lets say you have a
widget you want in the list.

stkWidget *w = new stkWidget ;
myItem->data = w;

You can even store something in the name field.

What you have to remember here is that the data and name fields are
automatically destroyed when the list is deleted. (One exception)

---------------------------

int  list_cleanall(sfcList  *);
int  list_delete(sfcList  *);


These are two functions that work alike.

list_cleanall() removes (and deletes) all the items in the list, and finally there
are no items in the list and its count is zero.

list_delete() works exactly as the above, but it also deletes the pointer and
the memory associated with it. Any later reference to the list will segfault.

Theoritically, list_cleanall() is actually list_delete() and then list_create().

[But internally it doesnt work that way. list_delete() calls list_cleanall() and
then further deletes the List pointer. See the source, satisfy yourself :)]

---------------------------

sfcListItem *list_insert(sfcList *, char *name, int );

Inserts an Item internally [after/before] "name" and then returns the pointer to it.
After/Before is determined by the third integer argument.

---------------------------

int list_remove(sfcListItem *);

Remove an item and delete it.

Warning : name and data are not deleted. You will have to take care of that.
FIXME : Can I delete the name ??

This is because, you may want to use the data after it has been removed. And,
I dont think C++ 'new' operator and free are _very_ compatible. I simply dont know.

---------------------------

int list_isempty(sfcList *);

Simply tells you if the list is empty. Its just this :
   return ( list==NULL || list->count==0 );


---------------------------

3. Profiler
================

Since Seal 3 preview 4, a profiler has been included with sfcList. This
basically tells you the total number of items created and freed. Its useful,
when you create a list, but forget to delete it.

FIXME : This is buggy, so the free part doesnt work. Also how to get the sizeof the
data to be free'd ??


4. ToDo
================

List sorting. This would be a useful feature.


5. History
================

sfcList has evolved from preview 1 onwards. Initially, it was used to
store the widgets in the Window Manager Kernel, but the author found it very difficult
to maintain 5 or more different lists at the same time. This solved his problem.

It was first distributed with Preview 3.

_________________
Ganesh lives @
www.iamganesh.com
Back to top
View user's profile Send private message Visit poster's website MSN Messenger
orudge
Administrator


Joined: 07 Oct 2001
Posts: 1332
Location: United Kingdom

PostPosted: Tue Jul 30, 2002 2:40 pm    Post subject: Reply with quote

Interesting, apart from some of the language at the start - many of the other regulars know I dislike swearing...
_________________
Owen Rudge
http://www.owenrudge.net/

Currently Playing (last time I was online, anyway):
Back to top
View user's profile Send private message Visit poster's website AIM Address Yahoo Messenger MSN Messenger
Display posts from previous:   
Post new topic   Reply to topic    SEAL Forum Index -> Programming Related All times are GMT - 7 Hours
Page 1 of 1

 
Jump to:  
You cannot post new topics in this forum
You cannot reply to topics in this forum
You cannot edit your posts in this forum
You cannot delete your posts in this forum
You cannot vote in polls in this forum


Powered by phpBB © 2001, 2005 phpBB Group