cList Struct Reference

Inheritance diagram for cList

Inheritance graph

Collaboration diagram for cList:

Collaboration graph


Public Methods

struct cList* cList_ctor (struct cList *ptr_clist, int width)
void cList_dtor (struct cList *ptr_clist, int memory_flag)
void cList_AddItem (struct cList *ptr_clist, struct cObject *ptr_cobject)
void cList_AddItem_Ex (struct cList *ptr_clist, struct cObject *ptr_cobject, int number_items)
void cList_RemItem (struct cList *ptr_clist, struct cObject *ptr_cobject)
bool cList_proc (struct cList *ptr_clist, struct Message *ptr_message)
int cList_Sel (struct cList *ptr_clist)
void cList_Disconnect (struct cList *ptr_clist)
bool cList_Select (struct cList *ptr_clist)
void cList_update (struct cList *ptr_clist)
struct cClip* cList_GetParent (struct cList *ptr_clist)
void cList_Hide (struct cList *ptr_clist)
void cList_Show (struct cList *ptr_clist)
void cList_Disable (struct cList *ptr_clist)
void cList_Enable (struct cList *ptr_clist)
void cList_AddObj (struct cList *ptr_clist, struct cObject *ptr_object, int x, int y)
void cList_InsObj (struct cList *ptr_clist, struct cObject *ptr_object, int x, int y, int index)
void cList_RemObj (struct cClip *ptr_clist, struct cObject *ptr_object)
bool cList_SelectFirst (struct cList *ptr_clist)
bool cList_SelectPrev (struct cList *ptr_clist, bool round)
bool cList_SelectNext (struct cList *ptr_clist, bool round)
void cList_Scroll (struct cList *ptr_clist, struct rect_t *rectangle)
void cList_Scroll_Ex (struct cList *ptr_clist, int x, int y)
void cList_SendScroll (struct cList *ptr_clist)
int cList_GetShifty (struct cList *ptr_clist)
int cList_GetShiftx (struct cList *ptr_clist)
int cList_GetCount (struct cList *ptr_clist)
struct cObject* cList_get_by_index (struct cList *ptr_clist, int index)
int cList_FindObj (struct cList *ptr_clist, struct cObject *ptr_object)
struct cObject* cList_GetSelectedObject (struct cList *ptr_clist)

Detailed Description

This structure implements methods for working with a list and a menu. A cList object is a container for cItem, cXItem and cSItem objects.

To add these objects to a list, use the cList_AddItem function. To remove objects from a list or a menu use the cList_RemItem function.

When a message comes in, process it using the cList_proc function.

You must call the cList_ctor function before use and the cList_dtor function after use.

See also:
Controls

Member Function Documentation

void cList_AddItem ( struct cList * ptr_clist,
struct cObject * ptr_cobject )
 

Adds an object (a cItem object for instance) to a cList object.

Parameters:
ptr_clist   A pointer to the initialized cList object
ptr_cobject   A pointer to the initialized cObject
Returns:
None 
   #include <cywin.h>
     ...
   {
     int index;
     struct cList menu;
     struct module_t main_module;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[3] = {
                                           "Start",
                                           "High Score",
                                           "Exit"
                                          };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
       cItem_ctor( ptr_menu_item, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item );
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }
See also:
cList_AddItem_Ex, cList_RemItem.

void cList_AddItem_Ex ( struct cList * ptr_clist,
struct cObject * ptr_cobject,
int number_items )
 

The extended version of the cList_AddItem function.
Adds an object to a cList object in a specified position.

Parameters:
ptr_clist   A pointer to the initialized cList object
ptr_cobject   A pointer to the initialized cObject
number_items   The zero based position in the cList object
Returns:
None 
   #include <cywin.h>
     ...
   {
     int index;
     struct cList menu;
     struct module_t main_module;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[3] = {
                                           "Start",
                                           "High Score",
                                           "Exit"
                                          };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ));
       cItem_ctor( ptr_menu_item, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item, index );
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }
See also:
cList_AddItem, cList_RemItem.

void cList_AddObj ( struct cList * ptr_clist,
struct cObject * ptr_object,
int x,
int y )
 

Adds an object to the cList in position (x, y).

Parameters:
ptr_clist   A pointer to the initialized cList object
ptr_object   A pointer to the initialized cObject object
x   x-coordinate of the new object
y   y-coordinate of the new object
Returns:
None

void cList_Disable ( struct cList * ptr_clist )
 

Disables a cList object so that it cannot be selected.

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
None
See also:
cList_Enable.

void cList_Disconnect ( struct cList * ptr_clist )
 

Disconnects a cList from its parent object.

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
None

void cList_Enable ( struct cList * ptr_clist )
 

Enables a cList object so that it may be selected.

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
None
See also:
cList_Disable.

int cList_FindObj ( struct cList * ptr_clist,
struct cObject * ptr_object )
 

Returns a child object's index in the cList (or -1).

Parameters:
ptr_clist   A pointer to the initialized cList object
ptr_object   A pointer to the needed cObject
Returns:
The child's object's index in the cList (or -1)

int cList_GetCount ( struct cList * ptr_clist )
 

Returns a count of child objects.

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
The child objects count

struct cClip * cList_GetParent ( struct cList * ptr_clist )
 

Returns a pointer to the cClip of the parent object.

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
A pointer to the cClip of the parent object

struct cObject * cList_GetSelectedObject ( struct cList * ptr_clist )
 

Returns the currently selected object.

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
A pointer to the currently selected object 
    #include <cywin.h>
     ...
     struct cItem* ptr_selected_item;
     ...
     // Retrieves the pointer to the list item currently selected
     ptr_selected_item = cList_GetSelectedObject( ptr_list_object );
     ...

int cList_GetShiftx ( struct cList * ptr_clist )
 

Returns the 'x' coordinate shift (as a result of scrolling).

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
'x' coordinate shift (as a result of scrolling)

int cList_GetShifty ( struct cList * ptr_clist )
 

Returns the 'y' coordinate shift (as a result of scrolling).

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
'y' coordinate shift (as a result of scrolling).

void cList_Hide ( struct cList * ptr_clist )
 

Hides a cList object.

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
None 
   #include <cybiko.h>
   ...
   struct cList main_menu;
   ...
   case MSG_LOSTFOCUS: // Application has lost focus
        ...
        cList_Hide( &main_menu );
        break;
   ...
   case MSG_GOTFOCUS: // Application has focus
        ...
        cList_Show( &main_menu );
        break;
   ...
See also:
cList_Show.

void cList_InsObj ( struct cList * ptr_clist,
struct cObject * ptr_object,
int x,
int y,
int index )
 

Adds an object to the cList in position ( x, y ) with a z-position index (maximal index is on the top).

Parameters:
ptr_clist   A pointer to the initialized cList object
ptr_object   A pointer to the initialized cObject object
x   x-coordinate of the new object
y   y-coordinate of the new object
index   z-position of the new object
Returns:
None

void cList_RemItem ( struct cList * ptr_clist,
struct cObject * ptr_cobject )
 

Removes an object from a cList object.

Parameters:
ptr_clist   A pointer to the initialized cList object
ptr_cobject   A pointer to the initialized cObject
Returns:
None 
   #include <cywin.h>
     ...
   {
     int index;
     struct cList menu;
     struct module_t main_module;
     struct cItem* ptr_menu_item[3];
     static const char* sz_menu_text[3] = {
                                           "Start",
                                           "High Score",
                                           "Exit"
                                          };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item[index] = (struct cItem* )malloc ( sizeof ( struct cItem ) );
       cItem_ctor( ptr_menu_item + index, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item + index );
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     // "High Score"  will be removed from the list.
     cList_RemItem( &menu, ptr_menu_item + 1 );
     cItem_dtor( ptr_menu_item + 1 );
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }
See also:
cList_AddItem, cList_AddItem_Ex.

void cList_RemObj ( struct cClip * ptr_clist,
struct cObject * ptr_object )
 

Removes an object from a cList.

Parameters:
ptr_clist   A pointer to the initialized cList object
ptr_object   A pointer to the initialized cObject object
Returns:
None

void cList_Scroll ( struct cList * ptr_clist,
struct rect_t * rectangle )
 

Scrolls a cList to make a rectangle visible.
Provides minimal scrolling.

Parameters:
ptr_clist   A pointer to the initialized cList object
rectangle   A pointer to the initialized rect_t structure
Returns:
None
See also:
cList_Scroll_Ex.

void cList_Scroll_Ex ( struct cList * ptr_clist,
int x,
int y )
 

Scrolls a cList by (x, y), but cannot exceed the child's boundaries.

Parameters:
ptr_clist   A pointer to the initialized cList object
x   "x" coordinate shift
y   "y" coordinate shift
Returns:
None
See also:
cList_Scroll.

int cList_Sel ( struct cList * ptr_clist )
 

Returns the index of the currently selected object.

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
The index of the currently selected object 
   #include <cywin.h>
     ...
   {
     struct cList menu;
     struct module_t main_module;
     struct Message* ptr_message;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[3] = {
                                           "Start",
                                           "High Score",
                                           "Exit"
                                          };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
       cItem_ctor( ptr_menu_item, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item );
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     if ( ptr_message->msgid == MSG_KEYDOWN )
     {
       if( Message_get_key_param( ptr_message )->scancode == KEY_ENTER )
       {
         switch ( cList_Sel( &menu ) )
         {
           case 0:
           ...
         }
       }
       //  Now we can select menu items using up and down arrows.
       cList_proc( &menu, ptr_message );
     }
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }

bool cList_Select ( struct cList * ptr_clist )
 

Selects a cList object.

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
TRUE if the cList object was selected

bool cList_SelectFirst ( struct cList * ptr_clist )
 

Selects the first object in the cList.

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
FALSE if the function failed

bool cList_SelectNext ( struct cList * ptr_clist,
bool round )
 

Selects the next object in the cList.

Parameters:
ptr_clist   A pointer to the initialized cList object
round   TRUE if you need to select the last object after selecting the first
Returns:
FALSE if the function failed

bool cList_SelectPrev ( struct cList * ptr_clist,
bool round )
 

Selects the previous object in the cList.

Parameters:
ptr_clist   A pointer to the initialized cList object
round   TRUE if you need to select the last object after selecting the first
Returns:
FALSE if function failed.

void cList_SendScroll ( struct cList * ptr_clist )
 

Forces this object to redraw its scrolling arrows.

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
None

void cList_Show ( struct cList * ptr_clist )
 

Shows a cList object.

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
None 
   #include <cybiko.h>
   ...
   struct cList main_menu;
   ...
   case MSG_LOSTFOCUS: // Application has lost focus
        ...
        cList_Hide( &main_menu );
        break;
   ...
   case MSG_GOTFOCUS: // Application has focus
        ...
        cList_Show( &main_menu );
        break;
   ...
See also:
cList_Hide.

struct cList * cList_ctor ( struct cList * ptr_clist,
int width )
 

Constructor.
Creates an empty cList object.

Parameters:
ptr_clist   A pointer to the cList structure
width   The width of a cList object.
Returns:
A pointer to the initialized cList object 
   #include <cywin.h>
     ...
   {
     int index;
     struct cList menu;
     struct module_t main_module;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[3] = {"Start",
                              "High Score",
                              "Exit"
                              };
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ));
       cItem_ctor( ptr_menu_item, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item);
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }

void cList_dtor ( struct cList * ptr_clist,
int memory_flag )
 

Destructor.
Deletes the cList object and all child objects (if any).

Parameters:
ptr_clist   A pointer to the initialized cList object
memory_flag   Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY to free it. Use LEAVE_MEMORY if the object was static or allocated in a stack
Returns:
None 
   #include <cywin.h>
     ...
   {
     int index;
     struct cList menu;
     struct module_t main_module;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[3] = {
                                           "Start",
                                           "High Score",
                                           "Exit"
                                          };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 ) ;
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ));
       cItem_ctor( ptr_menu_item, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item);
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }
See also:
FREE_MEMORY, LEAVE_MEMORY.

struct cObject * cList_get_by_index ( struct cList * ptr_clist,
int index )
 

Returns object index (or NULL).

Parameters:
ptr_clist   A pointer to the initialized cList object
index   The index of the object in cList
Returns:
The object's index (or NULL)

bool cList_proc ( struct cList * ptr_clist,
struct Message * ptr_message )
 

Message-processing function.

Parameters:
ptr_clist   A pointer to the initialized cList object
ptr_message   A pointer to the Message structure
Returns:
TRUE if the message was processed 
   #include <cywin.h>
     ...
   {
     struct cList menu;
     struct module_t main_module;
     struct Message* ptr_message;
     struct cItem* ptr_menu_item;
     static const char* sz_menu_text[3] = {
                                           "Start",
                                           "High Score",
                                           "Exit"
                                          };
     ...
     init_module( &main_module );
     ...
     cList_ctor( &menu, 100 );
     for( index = 0; index < 3; index++ )
     {
       ptr_menu_item = (struct cItem* )malloc ( sizeof ( struct cItem ) );
       cItem_ctor( ptr_menu_item, 100, sz_menu_text[index], FALSE, NULL, NULL );
       cList_AddItem( &menu, ptr_menu_item );
     }
     // Puts the cList object on the Cybiko screen.
     cWinApp_AddObj( main_module.m_process, &menu, 10, 40 );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     if ( ptr_message->msgid == MSG_KEYDOWN )
     {
       //  Now we can select menu items using up and down arrows.
       cList_proc( &menu, ptr_message );
     }
     ...
     // Menu items will be destroyed automatically.
     cList_dtor( &menu, LEAVE_MEMORY );
   }

void cList_update ( struct cList * ptr_clist )
 

Updates a cList object.

Parameters:
ptr_clist   A pointer to the initialized cList object
Returns:
None 
   #include <cybiko.h>
   ...
   struct cList main_menu;
   ...
   // Redraws the menu object and the screen
   cList_update( &main_menu );
   ...