cCustomForm Struct Reference

Inheritance diagram for cCustomForm

Inheritance graph

Collaboration diagram for cCustomForm:

Collaboration graph


Public Methods

struct cCustomForm* cCustomForm_ctor (struct cCustomForm *ptr_custom_form, struct rect_t *rect, char *name, bool round, struct cWinApp *ptr_win_app)
void cCustomForm_dtor (struct cCustomForm *ptr_custom_form, int memory_flag)
int cCustomForm_ShowModal (struct cCustomForm *ptr_custom_form)
bool cCustomForm_proc (struct cCustomForm *ptr_custom_form, struct Message *ptr_message)
void cCustomForm_Disconnect (struct cCustomForm *ptr_custom_form)
bool cCustomForm_Select (struct cCustomForm *ptr_custom_form)
void cCustomForm_update (struct cCustomForm *ptr_custom_form)
struct cClip* cCustomForm_GetParent (struct cCustomForm *ptr_custom_form)
void cCustomForm_Hide (struct cCustomForm *ptr_custom_form)
void cCustomForm_Show (struct cCustomForm *ptr_custom_form)
void cCustomForm_Disable (struct cCustomForm *ptr_custom_form)
void cCustomForm_Enable (struct cCustomForm *ptr_custom_form)
void cCustomForm_AddObj (struct cCustomForm *ptr_custom_form, struct cObject *ptr_object, int x, int y)
void cCustomForm_InsObj (struct cCustomForm *ptr_custom_form, struct cObject *ptr_object, int x, int y, int index)
void cCustomForm_RemObj (struct cCustomForm *ptr_custom_form, struct cObject *ptr_object)
bool cCustomForm_SelectFirst (struct cCustomForm *ptr_custom_form)
bool cCustomForm_SelectPrev (struct cCustomForm *ptr_custom_form, bool round)
bool cCustomForm_SelectNext (struct cCustomForm *ptr_custom_form, bool round)
void cCustomForm_Scroll (struct cCustomForm *ptr_custom_form, struct rect_t *rectangle)
void cCustomForm_Scroll_Ex (struct cCustomForm *ptr_custom_form, int x, int y)
void cCustomForm_SendScroll (struct cCustomForm *ptr_custom_form)
int cCustomForm_GetShifty (struct cCustomForm *ptr_custom_form)
int cCustomForm_GetShiftx (struct cCustomForm *ptr_custom_form)
int cCustomForm_GetCount (struct cCustomForm *ptr_custom_form)
struct cObject* cCustomForm_get_by_index (struct cCustomForm *ptr_custom_form, int index)
int cCustomForm_FindObj (struct cCustomForm *ptr_custom_form, struct cObject *ptr_object)
struct cObject* cCustomForm_GetSelectedObject (struct cCustomForm *ptr_custom_form)

Public Attributes

char FormNameString [30]
char Type
struct cWinApp* CurrApplication
struct cClip* ClientArea
int ModalResult
int HelpContext

Detailed Description

This is the main form structure, used to produce full-screen rectangle and rounded-rectangle windows (forms). Forms are useful for creating non-game applications. These applications usually consist of one or more hierarchically organized screens or windows, and the user moves between them in accordance with its hierarchy.

To achieve this using forms, you should simply derive one cCustomForm structure for every window you need. Then in your application, create your main window's object and call its cCustomForm_ShowModal method. If you need to show another window somewhere, create the object of the form structure you need and fill the form fields. Then call its ShowModal method, read the save form data, and delete the form.

You can also create non-modal windows, if you need to. After creating a form, you can view it (see cCustomForm_Show). When a message comes in, call the form's cCustomForm_Proc function to process it. The key is one form per screen or window.

You must call the cCustomForm_ctor function before use and the cCustomForm_dtor function after use.

See also:
Forms & Containers

Member Function Documentation

void cCustomForm_AddObj ( struct cCustomForm * ptr_custom_form,
struct cObject * ptr_object,
int x,
int y )
 

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

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
ptr_object   A pointer to the initialized cObject structure
x   The x-coordinate of the new object
y   The y-coordinate of the new object
Returns:
None 
   #include <cywin.h>
   ...
   ptr_menu_form = (struct cCustomForm*) malloc( sizeof *ptr_menu_form );
   ...
   form_rect.x = 40;
   form_rect.y = 20;
   form_rect.w = 86;
   form_rect.h = 60;
   ...
   cCustomForm_ctor( ptr_menu_form, &form_rect, "Main Menu",
     TRUE, ptr_win_app );
   ...
   ptr_menu_form->HelpContext = 0;
   ptr_menu_form->ModalResult = mrNone;
   ...
   // Adds the menu to the menu form
   cCustomForm_AddObj( ptr_menu_form, ptr_menu, 0, 0 );
   ...
   cCustomForm_Hide( ptr_menu_form );
   ...
   // Creates text
   ptr_text = (struct cText*) malloc( sizeof *ptr_text );
   ...
   cText_ctor( ptr_text, "Press <Enter>", cool_normal_font, CLR_BLACK );
   ...
   // Adds the text to the main form
   cFrameForm_AddObj( ptr_form, ptr_text, 42, 35 );
   ...

void cCustomForm_Disable ( struct cCustomForm * ptr_custom_form )
 

Disables the cCustomForm object so that it cannot be selected.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Returns:
None
See also:
cCustomForm_Enable.

void cCustomForm_Disconnect ( struct cCustomForm * ptr_custom_form )
 

Disconnects a cCustomForm from its parent object.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Returns:
None

void cCustomForm_Enable ( struct cCustomForm * ptr_custom_form )
 

Enables a cCustomForm object so that it may be selected.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Returns:
None
See also:
cCustomForm_Disable.

int cCustomForm_FindObj ( struct cCustomForm * ptr_custom_form,
struct cObject * ptr_object )
 

Returns the child object index in a cCustomForm (or -1 if the object was not found).

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
ptr_object   A pointer to the initialized cObject structure
Returns:
The child object index in cCustomForm (or -1 if the object was not found)

int cCustomForm_GetCount ( struct cCustomForm * ptr_custom_form )
 

Returns the count of child objects.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Returns:
Child objects count

struct cClip * cCustomForm_GetParent ( struct cCustomForm * ptr_custom_form )
 

Returns a pointer to the parent object.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Returns:
A pointer to the parent object

struct cObject * cCustomForm_GetSelectedObject ( struct cCustomForm * ptr_custom_form )
 

Returns the currently selected object.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Returns:
The currently selected object

int cCustomForm_GetShiftx ( struct cCustomForm * ptr_custom_form )
 

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

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Returns:
'x' coordinate shift (as a result of scrolling)

int cCustomForm_GetShifty ( struct cCustomForm * ptr_custom_form )
 

Forces this object to redraw its scrolling arrows.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Returns:
'y' coordinate shift (at result of scrolling)

void cCustomForm_Hide ( struct cCustomForm * ptr_custom_form )
 

Hides a cCustomForm object.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Returns:
None 
   #include <cywin.h>
   ...
   ptr_menu_form = (struct cCustomForm*) malloc( sizeof *ptr_menu_form );
   ...
   form_rect.x = 40;
   form_rect.y = 20;
   form_rect.w = 86;
   form_rect.h = 60;
   ...
   cCustomForm_ctor( ptr_menu_form, &form_rect, "Main Menu",
     TRUE, ptr_win_app );
   ...
   ptr_menu_form->HelpContext = 0;
   ptr_menu_form->ModalResult = mrNone;
   ...
   // Adds the menu to the menu form
   cCustomForm_AddObj( ptr_menu_form, ptr_menu, 0, 0 );
   ...
   cCustomForm_Hide( ptr_menu_form );
   ...
   // Creates text
   ptr_text = (struct cText*) malloc( sizeof *ptr_text );
   ...
   cText_ctor( ptr_text, "Press <Enter>", cool_normal_font, CLR_BLACK );
   ...
   // Adds the text to the main form
   cFrameForm_AddObj( ptr_form, ptr_text, 42, 35 );
   ...
See also:
cCustomForm_Show.

void cCustomForm_InsObj ( struct cCustomForm * ptr_custom_form,
struct cObject * ptr_object,
int x,
int y,
int index )
 

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

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
ptr_object   A pointer to the initialized cObject structure
x   The x-coordinate of the new object
y   The y-coordinate of the new object
index   The z-position of the new object
Returns:
None

void cCustomForm_RemObj ( struct cCustomForm * ptr_custom_form,
struct cObject * ptr_object )
 

Removes an object from a cCustomForm.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
ptr_object   A pointer to the initialized cObject structure
Returns:
None

void cCustomForm_Scroll ( struct cCustomForm * ptr_custom_form,
struct rect_t * rectangle )
 

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

Parameters:
ptr_custom_form   A pointer to initialized cCustomForm structure
rectangle   A pointer to the initialized rect_t structure
Returns:
None
See also:
cCustomForm_Scroll_Ex.

void cCustomForm_Scroll_Ex ( struct cCustomForm * ptr_custom_form,
int x,
int y )
 

Scrolls a cCustomForm by ( x, y ), but will not exceed the child's boundaries.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
x   "x" coordinate shift
y   "y" coordinate shift
Returns:
None
See also:
cCustomForm_Scroll.

bool cCustomForm_Select ( struct cCustomForm * ptr_custom_form )
 

Selects a cCustomForm object.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Returns:
TRUE if the object was selected.

bool cCustomForm_SelectFirst ( struct cCustomForm * ptr_custom_form )
 

Selects the first object in the cCustomForm.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Returns:
FALSE if the function failed

bool cCustomForm_SelectNext ( struct cCustomForm * ptr_custom_form,
bool round )
 

Selects the next object in the cCustomForm.

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

bool cCustomForm_SelectPrev ( struct cCustomForm * ptr_custom_form,
bool round )
 

Selects the previous object in the cCustomForm.

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

void cCustomForm_SendScroll ( struct cCustomForm * ptr_custom_form )
 

Forces this object to redraw its scrolling arrows.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Returns:
None

void cCustomForm_Show ( struct cCustomForm * ptr_custom_form )
 

Shows a cCustomForm object.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Returns:
None 
   #include <cywin.h>
   ...
   int cMainMenu_ShowModal( struct cCustomForm* ptr_form )
   {
    cCustomForm_Show( ptr_form );
    ...
    ptr_form->ModalResult = mrNone;
    ...
    while( ptr_form->ModalResult == mrNone )
    {
      struct Message* ptr_message =
        cWinApp_get_message( ptr_form->CurrApplication, 0, 1, MSG_USER );
      ...
      cMainMenu_proc( ptr_form, ptr_message );
      ...
      cCustomForm_update( ptr_form );
      ...
      Message_delete( ptr_message );
    }
    return ptr_form->ModalResult;
   }
   ...
See also:
cCustomForm_Hide.

int cCustomForm_ShowModal ( struct cCustomForm * ptr_custom_form )
 

Shows a form in modal mode.
This function shows the form and enters it to the message loop. The loop continues until anyone ModalResult variable is set to a non-zero value, or until a MSG_QUIT or MSG_SHUTUP messages is received. If these messages are received, the function reposts them to the application and leaves the message loop. This is how all forms will close when the applications ends.

Parameters:
ptr_custom_form   A pointer to a cCustomForm object
Returns:
tMResults value. mrNone(Zero) if MSG_QUIT or MSG_SHUTUP messages initiates leaving the loop See tMResults enum for predefined results 
   #include <cywin.h>
     ...
     struct cCustomForm custom_form;
     struct rect_t rect;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cCustomForm_ctor( &custom_form, &rect, "Caption", TRUE, main_module.m_process );
     cCustomForm_ShowModal( &custom_form );
     ...
     cCustomForm_dtor( &custom_form, LEAVE_MEMORY );
See also:
cCustomForm_ctor , MSG_QUIT , MSG_SHUTUP

struct cCustomForm * cCustomForm_ctor ( struct cCustomForm * ptr_custom_form,
struct rect_t * rect,
char * name,
bool round,
struct cWinApp * ptr_win_app )
 

Constructor.
Creates a cCustomForm object.

Parameters:
ptr_custom_form   A pointer to a cCustomForm object
rect   A window rectangle. If you want to create a full-screen form, you must set 'rect' to {-2,-2,164,104}
name   The form header caption. If NULL, the form has no header
round   If TRUE, the form shows a rectangle window with rounded corners; otherwise the form shows a plain rectangular window
ptr_win_app   A pointer to a cWinApp object. If NULL, the form will not be added to any application, so you can't use it in modal mode. Don't call cCustomForm_ShowModal if you set ptr_win_app to NULL. The forms are hidden, when created. To show them, use the cCustomForm_Show() or cCustomForm_ShowModal() functions.
Returns:
A pointer to the initialized cCustomForm object 
    #include <cywin.h>
      ...
      struct cCustomForm custom_form;
      struct rect_t rect;
      struct module_t main_module;
      ...
      init_module( &main_module );
      ...
      cCustomForm_ctor( &custom_form, &rect, "Caption", TRUE, main_module.m_process );
      cCustomForm_ShowModal( &custom_form );
      ...
      cCustomForm_dtor( &custom_form, LEAVE_MEMORY );

void cCustomForm_dtor ( struct cCustomForm * ptr_custom_form,
int memory_flag )
 

Deletes a cCustomForm object.

Parameters:
ptr_custom_form   A pointer to a cCustomForm 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 stack.
Returns:
None 
   #include <cywin.h>
     ...
     struct cCustomForm custom_form;
     struct rect_t rect;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cCustomForm_ctor( &custom_form, &rect, "Caption", TRUE, main_module.m_process );
     cCustomForm_ShowModal( &custom_form );
     ...
     cCustomForm_dtor( &custom_form, LEAVE_MEMORY );
See also:
FREE_MEMORY, LEAVE_MEMORY.

struct cObject * cCustomForm_get_by_index ( struct cCustomForm * ptr_custom_form,
int index )
 

Returns the object index.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Index   of object
Returns:
A pointer to the object

bool cCustomForm_proc ( struct cCustomForm * ptr_custom_form,
struct Message * ptr_message )
 

The message-processing function.

Parameters:
ptr_custom_form   A pointer to a cCustomForm object
ptr_message   A pointer to the processed message
Returns:
TRUE if the message was processed 
   #include <cywin.h>
     ...
     struct cCustomForm custom_form;
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     cCustomForm_ctor( &custom_form, &rect, "Caption", TRUE, main_module.m_process );
     ...
     // Adding some objects to the custom form.
     ...
     cCustomForm_Show( &custom_form );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     if ( ptr_message->msgid == MSG_KEYDOWN )
     {
       //  If 'Tab' was pressed, the next form's object will receive the focus.
       cCustomForm_proc( &custom_form, ptr_message );
     }
     ...
     cCustomForm_dtor( &custom_form, LEAVE_MEMORY );

void cCustomForm_update ( struct cCustomForm * ptr_custom_form )
 

Updates a cCustomForm object.

Parameters:
ptr_custom_form   A pointer to the initialized cCustomForm structure
Returns:
None 
   #include <cywin.h>
   ...
   int cMainMenu_ShowModal( struct cCustomForm* ptr_form )
   {
    cCustomForm_Show( ptr_form );
    ...
    ptr_form->ModalResult = mrNone;
    ...
    while( ptr_form->ModalResult == mrNone )
    {
      struct Message* ptr_message =
        cWinApp_get_message( ptr_form->CurrApplication, 0, 1, MSG_USER );
      ...
      cMainMenu_proc( ptr_form, ptr_message );
      ...
      cCustomForm_update( ptr_form );
      ...
      Message_delete( ptr_message );
     }
     return ptr_form->ModalResult;
   }
   ...

Member Data Documentation

struct cClip * ClientArea
 

The client area of the form.
All "normal" objects are added to the form's client area, including all free form space, and excluding the header and border.

struct cWinApp * CurrApplication
 

Parent application.

char FormNameString[30]
 

Form caption.

int HelpContext
 

Window help context.
You can set it to a non-zero value in the 0..999 range, and, when the '<?>' key is pressed, the help file named '<your value>.help' will be showed. The default value is zero.

int ModalResult
 

Result of form or dialog.
Modal forms run while the ModalResult is zero. When you set it to non-zero value, the modal cycle is canceled and ShowModal() returns ModalResult value. There are some predefined values (see tMResults). ModalResult can be set automatically, when you press <Esc> in the form, or when you press the in-form cButton.

char Type
 

Form type (rect or rounded box).