AppGeneric Struct Reference

Inheritance diagram for AppGeneric

Inheritance graph

Collaboration diagram for AppGeneric:

Collaboration graph


Public Methods

struct DisplayGraphics* AppGeneric_init_display (void)
void AppGeneric_clear_screen (void)
bool AppGeneric_proc (struct AppGeneric *ptr_app_generic, struct Message *ptr_message)
void AppGeneric_cancel_shutup (struct AppGeneric *ptr_app_generic)
void AppGeneric_ext_cancel_shutup (void)
bool AppGeneric_pause (struct AppGeneric *ptr_app_generic, clock_t timeout)
struct Process* AppGeneric_request_focus (struct Process *ptr_app_generic)
bool AppGeneric_has_focus (struct AppGeneric *ptr_app_generic)
struct DisplayGraphics* AppGeneric_get_display (void)
struct Message* AppGeneric_peek_message (struct AppGeneric *ptr_app_generic, bool remove, int min, int max)
struct Message* AppGeneric_get_message (struct AppGeneric *ptr_app_generic, long timeout, int min, int max)
void AppGeneric_put_message (struct AppGeneric *ptr_app_generic, struct Message *ptr_message)
char* AppGeneric_get_name (struct AppGeneric *ptr_app_generic)

Detailed Description

AppGeneric is a simple application structure. In other words, it is the base structure for applications. It implements such functions as: receiving the graphics context for application needs, cleaning the screen, processing messages and canceling MSG_SHUTUP events. This object cannot be instantiated! It can be obtained using init_module().

See also:
Application

Member Function Documentation

void AppGeneric_cancel_shutup ( struct AppGeneric * ptr_app_generic )
 

Cancels the MSG_SHUTUP message.
Cancels a task switch operation previously launched by another application in the task manager, and deletes any MSG_SHUTUP messages from the message queue. Requires the AppGeneric object pointer.

Parameters:
ptr_app_generic   A pointer to initialized AppGeneric object.
Returns:
None 
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       struct Message* ptr_message;
       ...
       ptr_message = AppGeneric_get_message( main_module.m_process,
                                             0,
                                             1,
                                             MSG_USER );
       if( ptr_message->msgid == MSG_SHUTUP )
       {
         //  We do not need to exit.
         //  Cancels shutup and deletes all MSG_SHUTUP messages.
         AppGeneric_cancel_shutup(  main_module.m_process );
         ...
       }
       ...
See also:
MSG_SHUTUP

void AppGeneric_clear_screen ( void )
 

Clears the screen with a white color.

Returns:
None 
       #include <cybiko.h>
       ...
       struct DisplayGraphics* ptr_gfx;
       ...
       //  Clears the screen.
       AppGeneric_clear_screen();
       ...
       //  Draws a filled rectangle.
       ptr_gfx = AppGeneric_init_display();
       DisplayGraphics_set_color( ptr_gfx , CLR_BLACK );
       DisplayGraphics_fill_rect( ptr_gfx , 5, 5, 30, 30 );
       DisplayGraphics_show( ptr_gfx );
       ...

void AppGeneric_ext_cancel_shutup ( void )
 

Cancels the MGS_SHUTUP message statically.
Used to cancel a task switch operation previously launched by another application in the task manager. Doesn't require the AppGeneric object pointer, but doesn't delete any MSG_SHUTUP messages.

Returns:
None 
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       struct Message* ptr_message;
       ...
       ptr_message = AppGeneric_get_message( main_module.m_process,
                                             0,
                                             1,
                                             MSG_USER );
       if( ptr_message->msgid == MSG_SHUTUP )
       {
         //  We do not need to exit.
         //  Cancels shutup.
         AppGeneric_ext_cancel_shutup();
         ...
       }
       ...
See also:
MSG_SHUTUP

struct DisplayGraphics * AppGeneric_get_display ( void )
 

Retrieves DisplayGraphics object to access the Cybiko computer's 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.
      DisplayGraphics_draw_bitmap( AppGeneric_get_display(),
                                   &bmp,
                                   30,
                                   40,
                                   BM_NORMAL );
      DisplayGraphics_show( AppGeneric_get_display() );
      ...
      Bitmap_dtor( &bmp, LEAVE_MEMORY );
      ...

struct Message * AppGeneric_get_message ( struct AppGeneric * ptr_app_generic,
long timeout,
int min,
int max )
 

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

Parameters:
ptr_app_generic   A pointer to initialized AppGeneric object
timeout   Timeout value(in milliseconds)
min   Deprecated
max   Deprecated
Returns:
Pointer to the Message if there is one 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 = AppGeneric_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 'Esc' key.
         }
       }
       ...
       Message_delete( ptr_message );
       ...
See also:
AppGeneric_put_message, AppGeneric_peek_message.

char * AppGeneric_get_name ( struct AppGeneric * ptr_app_generic )
 

Retrieves the name of the application.

Parameters:
ptr_app_generic   A pointer to an initialized AppGeneric object
Returns:
The name of the application 
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       TRACE( "Hello from the %s application",
             AppGeneric_get_name( main_module.m_process ) );
       ...

bool AppGeneric_has_focus ( struct AppGeneric * ptr_app_generic )
 

Tests whether the process has the device's focus.

Parameters:
ptr_app_generic   A pointer to an initialized AppGeneric object
Returns:
TRUE if the application has the focus 
      #include <cybiko.h>
      ...
      struct module_t main_module;
      ...
      init_module( &main_module );
      ...
      AppGeneric_request_focus( main_module.m_process );
      ...
      if( AppGeneric_has_focus( main_module.m_process ) )
      {
        // Draws something.
        ...
      }
      ...

struct DisplayGraphics * AppGeneric_init_display ( void )
 

Obtains the graphics context.

Returns:
A pointer to a DisplayGraphics object 
       #include <cybiko.h>
       ...
       struct DisplayGraphics* ptr_gfx;
       ...
       // Clears the screen.
       AppGeneric_clear_screen();
       ...
       // Draws a filled rectangle.
       ptr_gfx = AppGeneric_init_display();
       DisplayGraphics_set_color( ptr_gfx , CLR_BLACK );
       DisplayGraphics_fill_rect( ptr_gfx , 5, 5, 30, 30 );
       DisplayGraphics_show( ptr_gfx );
       ...

bool AppGeneric_pause ( struct AppGeneric * ptr_app_generic,
clock_t timeout )
 

Pauses execution of the application.

Parameters:
ptr_app_generic   A pointer to an initialized AppGeneric object
timeout   The time span for sleeping
Returns:
FALSE if timeout has passed 
       #include <cybiko.h>
       ...
       struct module_t main_module;
       ...
       init_module( &main_module );
       ...
       play_tone( 30 );
       AppGeneric_pause( main_module.m_process, 200 );
       play_tone( -1 );
       ...

struct Message * AppGeneric_peek_message ( struct AppGeneric * ptr_app_generic,
bool remove,
int min,
int max )
 

Peeks or gets a 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 it unless you really need to.

Parameters:
ptr_app_generic   A pointer to the initialized AppGeneric object
remove   If TRUE, the message will be removed from the message queue
min   Specifies the integer value of the lowest message value to be retrieved
max   Specifies the integer value of the highest message value to be retrieved
Returns:
Pointer to the Message if there is one 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 = AppGeneric_peek_message( main_module.m_process,
                                                     TRUE,
                                                     MSG_KEYDOWN,
                                                     MSG_KEYDOWN ) )
       {
         Message_delete( ptr_message );
       }
       ...
See also:
AppGeneric_get_message.

bool AppGeneric_proc ( struct AppGeneric * ptr_app_generic,
struct Message * ptr_message )
 

Provides generic message processing.
Should be called on every message that the user doesn't process.

Parameters:
ptr_app_generic   A pointer to the initialized AppGeneric object
ptr_message   A pointer to aprocessed Message
Returns:
TRUE if the message was processed 
       #include <cybiko.h>
       ...
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       //  Sets the resource "0.help" as the help file
       main_module.m_process->HelpContext = 0;
       ptr_message = AppGeneric_get_message( main_module.m_process,
                                             0,
                                             1,
                                             MSG_USER );
       //  The help screen appears if the user presses the '?' button
       AppGeneric_proc( main_module.m_process, ptr_message );
       ...

void AppGeneric_put_message ( struct AppGeneric * ptr_app_generic,
struct Message * ptr_message )
 

Puts a Message in the application's Queue.

Parameters:
ptr_app_generic   A pointer to the initialized AppGeneric 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 = AppGeneric_get_message( main_module.m_process,
                                             0,
                                             1,
                                             MSG_MAKE_TASK );
       if( ptr_message->msgid == MSG_MAKE_TASK )
       {
         ...
         //  Performs some periodical calculation.
         ...
         sleep( 250 );
         AppGeneric_put_message( main_module.m_process, ptr_message );
       }
       else
       {
         Message_delete( ptr_message );
       }
       ...
See also:
Process_get_message, Process_peek_message.

struct Process * AppGeneric_request_focus ( struct Process * ptr_app_generic )
 

Requests that the application receive the focus.
The application with the focus 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 requested it and sends it the message MSG_GOTFOCUS. After that, the system sends the message MSG_LOSTFOCUS to the process that had the focus before this call.

Parameters:
ptr_app_generic   A pointer to the initialized AppGeneric object
Returns:
A pointer to the Process object that had the focus before this call 
      #include <cybiko.h>
      ...
      struct module_t main_module;
      ...
      init_module( &main_module );
      ...
      AppGeneric_request_focus( main_module.m_process );
      ...
      if( AppGeneric_has_focus( main_module.m_process ) )
      {
        //  Draws something.
        ...
      }
      ...
See also:
MSG_GOTFOCUS, MSG_LOSTFOCUS