Process Struct Reference

Inheritance diagram for Process

Inheritance graph

Collaboration diagram for Process:

Collaboration graph


Public Methods

bool Process_pause (struct Process *ptr_process, clock_t timeout)
struct Process* Process_request_focus (struct Process *ptr_process)
bool Process_has_focus (struct Process *ptr_process)
struct DisplayGraphics* Process_get_display (void)
char* Process_get_name (struct Process *ptr_process)
void Process_put_message (struct Process *ptr_process, struct Message *ptr_message)
struct Message* Process_get_message (struct Process *ptr_process, long timeout, int min, int max)
struct Message* Process_peek_message (struct Process *ptr_process, bool remove, int min, int max)

Detailed Description

A thread enabled to process messages. The System has the Thread function to do tasks, and the Process function to process messages such as input events from the keyboard, system messages, and radio-sent communication messages. The Process function can have input focus; you can and ask for it by calling Process_request_focus(). When the Process has the focus, it gets all input events from the keyboard.

See also:
Processes and Modules

Member Function Documentation

struct DisplayGraphics * Process_get_display ( void )
 

Retrieves a DisplayGraphics object to the access display.

Returns:
A pointer to the DisplayGraphics object 
       #include <cybiko.h>
       ...
       struct Bitmap bmp;
       ...
       //  Creates a bitmap from the file "root.ico".
       Bitmap_ctor_Ex1( &bmp, "root.ico" );
       ...
       //  Draws bitmap.
       Graphics_draw_bitmap( Process_get_display(), &bmp, 30, 40, BM_NORMAL );
       ...
       Bitmap_dtor( &bmp, LEAVE_MEMORY );
       ...

struct Message * Process_get_message ( struct Process * ptr_process,
long timeout,
int min,
int max )
 

Returns the message after the specified interval.
The calling thread waits until the first message appears in the queue. Be careful not to overload the queue overflow. Delete message when you finished with it.

Parameters:
ptr_process   A pointer to the initialized Process object.
timeout   Timeout value(in milliseconds)
min   deprecated
max   deprecated
Returns:
Pointer to the Message if one is in the Process' queue, or 0 if a timeout occurs 
       #include <cybiko.h>
       ...
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       ptr_message = Process_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_ESC )
         {
           //  Processes key 'Esc'.
         }
       }
       ...
       Message_delete( ptr_message );
       ...
See also:
Process_peek_message.

char * Process_get_name ( struct Process * ptr_process )
 

Retrieves the Process' name.

Parameters:
ptr_process   A pointer to the initialized Process object
Returns:
The Process' name 
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       TRACE("Hello from the %s process",
             Process_get_name( main_module.m_process ) );
       ...

bool Process_has_focus ( struct Process * ptr_process )
 

Tests whether the Process has the focus.

Parameters:
ptr_process   A pointer to the initialized Process object
Returns:
TRUE if the Process has the focus, otherwise FALSE 
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       Process_request_focus( main_module.m_process );
       ...
       if( Process_has_focus( main_module.m_process ) )
       {
         //  Draws something.
         ...
       }
       ...

bool Process_pause ( struct Process * ptr_process,
clock_t timeout )
 

Pauses execution of the Process.

Parameters:
ptr_process   A pointer to the Process initialized object
timeout   The time span to sleep, in milliseconds
Returns:
FALSE if the timeout is passed 
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       play_tone(30);
       Process_pause(main_module.m_process, 200);
       play_tone(-1);
       ...

struct Message * Process_peek_message ( struct Process * ptr_process,
bool remove,
int min,
int max )
 

Peeks or gets message from the queue.
If remove is TRUE, the message will be removed. This function does not wait for a message to be available; it returns 0 immediately if there are no messages in the specified range. Don't use this function unless you really need to.

Parameters:
ptr_process   A pointer to the initialized Process object
remove   If TRUE the message will be removed from the message queue
min   Specifies the lowest message value to be retrieved, as an integer value
max   Specifies the highest message value to be retrieved, as an integer value
Returns:
A pointer to the Message if one is in the Process' queue, otherwise 0 
       #include <cybiko.h>
       ...
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       //  Removes all keyboard messages from the queue.
       while(ptr_message = Process_peek_message( main_module.m_process, TRUE, MSG_KEYDOWN, MSG_KEYDOWN ))
       {
         Message_delete( ptr_message );
       }
       ...
See also:
Process_get_message.

void Process_put_message ( struct Process * ptr_process,
struct Message * ptr_message )
 

Puts a Message in the Process' Queue.

Parameters:
ptr_process   A pointer to the initialized Process object
ptr_message   A pointer to the message to send
Returns:
None 
       #include <cybiko.h>
       ...
       #define MSG_MAKE_TASK  MSG_USER + 1
       ...
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       ptr_message = Process_get_message( main_module.m_process, 0, 1, MSG_MAKE_TASK );
       if( ptr_message->msgid == MSG_MAKE_TASK )
       {
         ...
         //  Performs some periodical calculation.
         ...
         Process_pause( main_module.m_process, 250 );
         Process_put_message( main_module.m_process, ptr_message );
       }
       else
       {
         Message_delete( ptr_message );
       }
       ...
See also:
Process_get_message , Process_peek_message.

struct Process * Process_request_focus ( struct Process * ptr_process )
 

Asks the system to activate the Process (pass the focus).
Once it has the focus, the Process has actual access to the screen and receives the keyboard and pointing device events. When the system gets this call, it passes the focus to the Process that asked for it by sending it the message MSG_GOTFOCUS. Then the system sends the message MSG_LOSTFOCUS to the Process that had the focus previously.

Parameters:
ptr_process   A pointer to the initialized Process object
Returns:
Process that had the focus before this call 
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       Process_request_focus( main_module.m_process );
       ...
       if( Process_has_focus( main_module.m_process ) )
       {
         //  Draws something.
         ...
       }
       ...