The OBJECT object

Seal is based on objects. Every object can own other object and all of them own others. The basic structure for this system is t_object structure that only sets some variables and consists of main functions.

For example: object "drivers" own objects "t_mouse" and "t_keyboard" and you can add other object by function (insert) ....see t_object structure. When function translate_event is called, it calls both of these objects and returns state of events in t_event structure. We explain this function later.


obj_init ()
     Description:
       Initializes a new OBJECT object.

     Syntax:
       p_object  obj_init ( p_object o );

     Parameters:
       o           Allocated memory to store the object in.

     Returns:
       The new t_object structure.




The t_object structure

Variables

     Name:         l_dword  tag;

     Description:  Id of object type. It's only information about 
                   object. Do not change this values, it is only  
                   for internal use. Possible values:

                   TAG_NONE    - No information set.
                   TAG_DISPOSE - When this tag is set, the object 
                                 is done or does not exist.
                   TAG_OBJECT  - Object inherits data from t_object.
                   TAG_VIEW    - Object inherits data from t_view.
                   TAG_WINDOW  - Object inherits data from t_window.
                   TAG_BUTTON  - Object inherits data from t_button.



     Name:         l_int  process_tick;

     Description:  Miliseconds that defines frequency of the calls to
                   function "func_callback(p_object o);" This milisec 
                   is set by "init_stillprocess(p_object o, l_int milisec);"
                   You can dispose a still-process by calling the function
                   "done_stillprocess(p_object o);". It's used for movie-
                   drawing for example, when you want to redraw your 
                   frames at each process_tick milisecond. If you want to 
                   redraw your frame each 20 milisecs, you redefine the
                   function "func_callback()" and point it to your own
                   function from where the draw function will be called.



     Name:         l_dword  state;

     Description:  Current status of object state of object can't be the
                   same in all objects. F.e. state of t_mouse object could
                   be one of O_SF_MOUSExxxx (see mouse.h) but in t_keyboard
                   it could be one of KB_SF_KEYxxxx (see keyboard.h), but
                   all of them must start their values from last OB_SF_xxxx 
                   value = 0x020, because it cannot be overlayed. 



     Name:         l_dword  options;

     Description:  Options of the object. All objects has some initial 
                   options and these set the first object's services.


  
     Name:         l_big  data_type;

     Description:  All of objects can store information to clipboard by 
                   the function "set_data()" and gets information from 
                   clipboard by the "get_data()" function. To know what 
                   type this object knows, it is used this variable. The 
                   object can know more than one type so it's better to 
                   use it as bit-combination. This types are also used 
                   for t_list.tag/t_item.tag variable and for object's 
                   t_data structure. Available types:

                   DAT_NONE    - No data type.
                   DAT_TEXT    - Single text ended by zero.
                   DAT_IMAGE   - Type of BITMAP.
                   DAT_TFILE   - A t_file structure.
                   DAT_LIST    - A pointer to list (p_list).
                   DAT_ALLKNOW - All data types are accepted.   



     Name:         p_object  owner;

     Description:  To know which parent is parent of object we use this 
                   pointer. If the owner is NULL it's ,,oldest parent".



     Name:         p_object  next;

     Description:  Points to the object that is after this object in the 
                   group where it's parent is "owner". The system is:

                    / <- next\  / <- next\  / <- next\
                   last  <-   3rd  <-    2nd   <-    1st  <-|
                    \ next ---------------------------------|



     Name:         p_object  prev;

     Description:  Is same as "next" but it points to the previous object.

                         / next = \  / next = \  / next = \
                   | -> last  ->   3rd  ->    2nd   ->  1st
                   |------------------------------- next /



     Name:         p_object  last;

     Description:  We also must know the pointer to where the sub-objects
                   are stored. For this purpose we use the pointer "last" 
                   which points to the last sub-object. When "last" is NULL 
                   it means this object is not a parent. Otherwise it is 
                   and "last->owner" = this object.




     Name:         l_char    reserved[48];

     Description:  Reserved for others variables




Functions:

done ()
     Description:
       Ends an object and removes it from it's group.

     Syntax:
       void  (*done) ( p_object o );

     Parameters:
       o           The object to end.

     Returns:
       -



owner_view ()
     Description:
       Gets the first graphic object. In this GUI can exist graphic 
       and not graphic objects. Graphic objects are defined by the 
       t_view struct, that we will explain more about later.

     Syntax:
       p_object  (*owner_view) ( p_object o );

     Parameters:
       o           The object to get the graphic object from.

     Returns:
       The first graphic object.



next_view ()
     Description:
       Gets the next visible object.

     Syntax:
       p_object  (*next_view) ( p_object o );

     Parameters:
       o          The parent object to look in.

     Returns:
       The next view in the group. 



prev_view ()
     Description:
       Gets the previous visible object.

     Syntax:
       p_object  (*prev_view) ( p_object o );

     Parameters:
       o          The parent object to look in.

     Returns:
       The previous view in the group. 



last_view ()
     Description:
       Gets the last visible object.

     Syntax:
       p_object  (*last_view) ( p_object o );

     Parameters:
       o          The parent object to look in.

     Returns:
       The last view in the group. 



first_view ()
     Description:
       Gets the first visible object.

     Syntax:
       p_object   (*first_view) ( p_object o );

     Parameters:
       o          The parent object to look in.

     Returns:
       The last first in the group. 



prev_view_to_first ()
     Description:
       Gets the previous view if it isn't the first one.

     Syntax:
       p_object  (*prev_view_to_first) ( p_object o );

     Parameters:
       o          The parent object to look in.

     Returns:
       If the previous view isn't the first, it is returned.
       Otherwise NULL is returned.



next_view_to_last ()
     Description:
       Gets the next view if it isn't the last one.

     Syntax:
       p_object   (*next_view_to_last) ( p_object o );

     Parameters:
       o          The parent object to look in.

     Returns:
       If the next view isn't the last, it is returned.
       Otherwise NULL is returned.



setup ()
     Description:
       This functions is always called when the object is put into 
       the group by the insert() function.

     Syntax:
       void  (*setup) ( p_object o );

     Parameters:
       o          The parent to put the object in.

     Returns:
       -



insert ()
     Description:
       Inserts an object into a group.

     Syntax:
       p_object  (*insert) ( p_object o, p_object sub );

     Parameters:
       o          The parent to put the object in.
       sub        The object to insert.

     Returns:
       The value of "sub".



insert_before ()
     Description:
       Inserts an object into a group before an exising object.

     Syntax:
       p_object   (*insert_before) ( p_object o, p_object sub,
                                     p_object before );

     Parameters:
       o          The parent to put the object in.
       sub        The object to insert.
       before     "sub" is inserted before this object.

     Returns:
       The value of "sub".



put_in_front_of ()
     Description:
       Replaces an object in the position before another object.

     Syntax:
       void  (*put_in_front_of) ( p_object o, p_object before );

     Parameters:
       o          The object to replace.
       before     "sub" is inserted before this object.

     Returns:
       -



remove ()
     Description:
       Removes an object from a group.

     Syntax:
       void  (*remove) ( p_object o, p_object sub );

     Parameters:
       o           The group to remove from.
       sub         Object to remove.

     Returns:
       -



first ()
     Description:
       Gets the first object in a group.

     Syntax:
       p_object  (*first) ( p_object o );

     Parameters:
       o           Group to get the object from.

     Returns:
       The first object.



func_callback ()
     Description:
       The function that will be called each process_tick, that 
       you select with the function "init_stillprocess();". 
       This function sets the options to "OB_OF_STILLPROCESS"
       and "process_tick" to miliseconds.

     Syntax:
       void  (*func_callback) ( p_object s );

     Parameters:
       s           The object to call for.

     Returns:
       -



set_state()
     Description:
       

     Syntax:
       void  (*set_state) ( p_object o, l_dword st, l_bool set );

     Parameters:
       o           Object to set the state for.
       st          The state to set/unset.
       set         If set to True, function sets the state. 
                   Otherwise the state is unset.

     Returns:
       -



set_options ()
     Description:
       Same as set_state() but sets options instead.

     Syntax:
       void  (*set_options) ( p_object o, l_dword op, l_bool set );

     Parameters:
       o           Object to set the state for.
       op          The option to set/unset.
       set         If set to True, function sets the state. 
                   Otherwise the state is unset.

     Returns:
       -



is_state ()
     Description:
       Checks if the "state" variable contains the defined flag.

     Syntax:
       l_bool  (*is_state) ( p_object o, l_dword st );

     Parameters:
       o           The object who's variable to check.
       st          Flag to check for.

     Returns:
       True if the flag is found. False if not found.



is_option
     Description:
       Checks if the "options" variable contains the defined flag.

     Syntax:
       l_bool  (*is_options) ( p_object o, l_dword op );


     Parameters:
       o           The object who's variable to check.
       op          Flag to check for.

     Returns:
       True if the flag is found. False if not found.



translate_event ()
     Description:
       This is the main function for event translating. Whenever an
       event occurs this function is called. Calling of functions in
       a group is by their positions. So the function that is preferred
       is called at the first position, then first object in the group 
       to the last object in the group.

     Syntax:
       void  (*translate_event) ( p_object o, t_event *event );

     Parameters:
       o           The object to call functions in.
       event       Name of the occurred event.

     Returns:
       -





The t_event structure

Variables:
     Name:         l_dword   type;

     Description:  Type of event (EV_MOUSE, EV_KEYBOARD, EV_MESSAGE etc.)



     Name:         p_object  obj;

     Description:  When the type of event is set, then "obj" point to the
                   object that set this type. F.e. when the type is 
                   EV_MOUSE the "obj" points to "mouse" object.