cDialog Struct Reference

Inheritance diagram for cDialog

Inheritance graph

Collaboration diagram for cDialog:

Collaboration graph


Public Methods

struct cDialog* cDialog_ctor (struct cDialog *ptr_dialog, char *caption, char *text, long style, int edit_size, struct cWinApp *ptr_win_app)
void cDialog_dtor (struct cDialog *ptr_dialog, int memory_flag)
void cDialog_GetEditText (struct cDialog *ptr_dialog, char *ptr_buffer)
void cDialog_SetEditText (struct cDialog *ptr_dialog, char *text)
void cDialog_PlaySound (long number)
bool cDialog_proc (struct cDialog *ptr_dialog, struct Message *ptr_message)
int cDialog_ShowModal (struct cDialog *ptr_dialog)
void cDialog_Disconnect (struct cDialog *ptr_dialog)
bool cDialog_Select (struct cDialog *ptr_dialog)
void cDialog_update (struct cDialog *ptr_dialog)
struct cClip* cDialog_GetParent (struct cDialog *ptr_dialog)
void cDialog_Hide (struct cDialog *ptr_dialog)
void cDialog_Show (struct cDialog *ptr_dialog)
void cDialog_Disable (struct cDialog *ptr_dialog)
void cDialog_Enable (struct cDialog *ptr_dialog)
void cDialog_AddObj (struct cDialog *ptr_dialog, struct cObject *ptr_object, int x, int y)
void cDialog_InsObj (struct cDialog *ptr_dialog, struct cObject *ptr_object, int x, int y, int index)
void cDialog_RemObj (struct cClip *ptr_dialog, struct cObject *ptr_object)
bool cDialog_SelectFirst (struct cDialog *ptr_dialog)
bool cDialog_SelectPrev (struct cDialog *ptr_dialog, bool round)
bool cDialog_SelectNext (struct cDialog *ptr_dialog, bool round)
void cDialog_Scroll (struct cDialog *ptr_dialog, struct rect_t *rectangle)
void cDialog_Scroll_Ex (struct cDialog *ptr_dialog, int x, int y)
void cDialog_SendScroll (struct cDialog *ptr_dialog)
int cDialog_GetShifty (struct cDialog *ptr_dialog)
int cDialog_GetShiftx (struct cDialog *ptr_dialog)
int cDialog_GetCount (struct cDialog *ptr_dialog)
struct cObject* cDialog_get_by_index (struct cDialog *ptr_dialog, int index)
int cDialog_FindObj (struct cDialog *ptr_dialog, struct cObject *ptr_object)
struct cObject* cDialog_GetSelectedObject (struct cDialog *ptr_dialog)

Detailed Description

This is a common dialog structure. You can create a various types of dialog windows using the third parameter of the cDialog_ctor function.

Dialog styles are defined by combinations of constants of the "tDialogStyle" enumeration (see the "Enumerations" page). For example, you can create a combination like this: "mbOk | mbCancel | mbEdit". This dialog box contains "Ok" and "Cancel" buttons, plus editing field that has been defined by the "mbEdit" parameter. In this case, both the cButton_GetEditText and cButton_SetEditText functions are enabled.

After creating a dialog box, you can show it (see cDialog_ShowModal), and then when a message comes in, you can process it by calling the cDialog_proc function.

You must call the cDialog_ctor function before use and the cDialog_dtor function after use.

See also:
Forms & Containers , cButton_GetEditText , cButton_SetEditText

Member Function Documentation

void cDialog_AddObj ( struct cDialog * ptr_dialog,
struct cObject * ptr_object,
int x,
int y )
 

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

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
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

void cDialog_Disable ( struct cDialog * ptr_dialog )
 

Disables cDialog object so that it cannot be selected.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
Returns:
None 
   #include <cywin.h>
       ...
       struct cDialog dialog;
       struct module_t main_module;
       struct Message* ptr_message;
       ...
       init_module( &main_module );
       ...
       cDialog_ctor( &dialog, NULL, str_Really_exit,
                     mbQuit | mbCancel | mbs1, 0, main_module.m_process );
       ...
       cDialog_Show( &dialog );
       ...
       cDialog_Disable( &dialog );
       ...
       cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
cDialog_Enable.

void cDialog_Disconnect ( struct cDialog * ptr_dialog )
 

Disconnects the cDialog from its parent object.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
Returns:
None

void cDialog_Enable ( struct cDialog * ptr_dialog )
 

Enables the cDialog object so that it may be selected.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
Returns:
None 
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, NULL, str_Really_exit,
                   mbQuit | mbCancel | mbs1, 0, main_module.m_process );
     ...
     cDialog_Show( &dialog );
     ...
     cDialog_Disable( &dialog );
     cDialog_Enable ( &dialog );
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
cDialog_Disable.

int cDialog_FindObj ( struct cDialog * ptr_dialog,
struct cObject * ptr_object )
 

Returns the child object index in the cDialog (or -1).

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
ptr_object   A pointer to the initialized cObject object
Returns:
Child object index in cDialog (or -1)

int cDialog_GetCount ( struct cDialog * ptr_dialog )
 

Returns the count of child objects.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
Returns:
Child objects count

void cDialog_GetEditText ( struct cDialog * ptr_dialog,
char * ptr_buffer )
 

Copies an edit string from the internal buffer into "ptr_buffer".
You must provide enough space for the buffer.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
ptr_buffer   A pointer to the allocated buffer
Returns:
None 
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     char sz_name[11];
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, "Name", "Enter your name:",
                     mbOk | mbCancel | mbEdit, 10, main_module.m_process );
     ...
     if ( cDialog_ShowModal( &dialog ) == mrOk )
     {
       cDialog_GetEditText( &dialog, sz_name );
     }
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
cDialog_SetEditText.

struct cClip * cDialog_GetParent ( struct cDialog * ptr_dialog )
 

Returns a pointer to the parent object.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
Returns:
A pointer to the parent object

struct cObject * cDialog_GetSelectedObject ( struct cDialog * ptr_dialog )
 

Returns the currently selected object.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
Returns:
Currently selected object

int cDialog_GetShiftx ( struct cDialog * ptr_dialog )
 

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

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
Returns:
x coordinate shift (as a result of scrolling)

int cDialog_GetShifty ( struct cDialog * ptr_dialog )
 

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

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
Returns:
y coordinate shift (as a result of scrolling)

void cDialog_Hide ( struct cDialog * ptr_dialog )
 

Hides the cDialog object.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
Returns:
None 
   #include <cywin.h>
    ...
    struct cDialog dialog;
    struct module_t main_module;
    struct Message* ptr_message;
    ...
    init_module( &main_module );
    ...
    cDialog_ctor( &dialog, NULL, str_Really_exit,
                    mbQuit | mbCancel | mbs1, 0, main_module.m_process );
    ...
    cDialog_Show( &dialog );
    ...
    cDialog_Hide( &dialog );
    ...
    cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
cDialog_Show.

void cDialog_InsObj ( struct cDialog * ptr_dialog,
struct cObject * ptr_object,
int x,
int y,
int index )
 

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

Parameters:
ptr_dialog   A pointer to the initialized cDialog object.
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 cDialog_PlaySound ( long number )
 

Plays the standard dialog sound.

Parameters:
number   The sound's number (from mbs0 to mbs6)
Returns:
None 
   #include <cywin.h>
   {
     ...
     struct cDialog dialog;
     struct module_t main_module;
     char sz_name[11];
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, "Name", "Enter your name:",
                     mbOk | mbCancel | mbEdit | mbs1, 10, main_module.m_process );
     ...
     cDialog_SetEditText( &dialog, "Bill Gates" );
     if ( cDialog_ShowModal( &dialog ) == mrOk )
     {
       cDialog_GetEditText( &dialog, sz_name );
       if( !strlen( sz_name ) )
       {
         cDialog_PlaySound( mbs2 );
       }
     }
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );
   }

void cDialog_RemObj ( struct cClip * ptr_dialog,
struct cObject * ptr_object )
 

Removes an object from the cDialog.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object.
ptr_object   A pointer to the initialized cObject structure
Returns:
None

void cDialog_Scroll ( struct cDialog * ptr_dialog,
struct rect_t * rectangle )
 

Scrolls cDialog to make rectangle visible.
Provides minimal scrolling.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object.
rectangle   A pointer to the initialized rect_t object.
Returns:
None
See also:
cDialog_Scroll_Ex.

void cDialog_Scroll_Ex ( struct cDialog * ptr_dialog,
int x,
int y )
 

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

Parameters:
ptr_dialog   A pointer to the initialized cDialog object.
x   "x" coordinate shift
y   "y" coordinate shift
Returns:
None
See also:
cDialog_Scroll.

bool cDialog_Select ( struct cDialog * ptr_dialog )
 

Selects a cDialog object.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
Returns:
TRUE if object was selected

bool cDialog_SelectFirst ( struct cDialog * ptr_dialog )
 

Selects the first object in the cDialog.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object.
Returns:
FALSE if the function failed.

bool cDialog_SelectNext ( struct cDialog * ptr_dialog,
bool round )
 

Selects the next object in the cDialog.

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

bool cDialog_SelectPrev ( struct cDialog * ptr_dialog,
bool round )
 

Selects the previous object in the cDialog.

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

void cDialog_SendScroll ( struct cDialog * ptr_dialog )
 

Forces this object to redraw its scrolling arrows.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
Returns:
None

void cDialog_SetEditText ( struct cDialog * ptr_dialog,
char * text )
 

Sets an initial string in an edit line.
Does not work if the mbEdit style is not defined.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
text   The text to show
Returns:
None 
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     char sz_name[11];
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, "Name", "Enter your name:",
                     mbOk | mbCancel | mbEdit, 10, main_module.m_process );
     ...
     cDialog_SetEditText( &dialog, "Bill Gates" );
     if ( cDialog_ShowModal( &dialog ) == mrOk )
     {
       cDialog_GetEditText( &dialog, sz_name );
     }
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
cDialog_GetEditText.

void cDialog_Show ( struct cDialog * ptr_dialog )
 

Shows a cDialog object.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
Returns:
None 
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, NULL, str_Really_exit,
                     mbQuit | mbCancel | mbs1, 0, main_module.m_process );
     ...
     cDialog_Show( &dialog );
     ...
     cDialog_Hide( &dialog );
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
cDialog_Hide.

int cDialog_ShowModal ( struct cDialog * ptr_dialog )
 

Shows a cDialog in modal mode.
This function shows the cDialog and enters it into the message loop. The loop continues until any one ModalResult variable is set a to non-zero value, or until a MSG_QUIT or MSG_SHUTUP message 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 application ends.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
Returns:
tMResults value. mrNone(Zero) if MSG_QUIT or MSG_SHUTUP messages initiates leaving the loop. There are some predefined results 
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     char sz_name[11];
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, "Name", "Enter your name:",
                     mbOk | mbCancel | mbEdit, 10, main_module.m_process );
     ...
     cDialog_SetEditText( &dialog, "Bill Gates" );
     if ( cDialog_ShowModal( &dialog ) == mrOk )
     {
       cDialog_GetEditText( &dialog, sz_name );
     }
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
tMResults , MSG_QUIT , MSG_SHUTUP.

struct cDialog * cDialog_ctor ( struct cDialog * ptr_dialog,
char * caption,
char * text,
long style,
int edit_size,
struct cWinApp * ptr_win_app )
 

Initializes a cDialog object.

Parameters:
ptr_dialog   A pointer to a cDialog object
caption   Dialog caption
text   Dialog text
style   Dialog style. The style is a combination of "tDialogStyle" constants
edit_size   Edit string size (in symbols). If mbEdit not defined in the style, this parameter is not used
ptr_win_app   A pointer to the structure of the current cywin application
Returns:
A pointer to the initialized cDialog object 
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, "Caption", "Dialog Text",
                     mbYes | mbNo, 0, main_module.m_process );
     ...
     cDialog_ShowModal( &dialog );
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );

void cDialog_dtor ( struct cDialog * ptr_dialog,
int memory_flag )
 

Destructor.
Deletes the cDialog object.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
memory_flag   Can be FREE_MEMORY or LEAVE_MEMORY. If the memory was allocated for the object by malloc(), use FREE_MEMORY. Use LEAVE_MEMORY if object was static or allocated in stack use LEAVE_MEMORY.
Returns:
None 
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, "Caption", "Dialog Text",
                     mbYes | mbNo, 0, main_module.m_process );
     ...
     cDialog_ShowModal( &dialog );
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );
See also:
FREE_MEMORY, LEAVE_MEMORY.

struct cObject * cDialog_get_by_index ( struct cDialog * ptr_dialog,
int index )
 

Returns the object's index (or NULL).

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
index   The object's index
Returns:
Object's index (or NULL)

bool cDialog_proc ( struct cDialog * ptr_dialog,
struct Message * ptr_message )
 

Message-processing function.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
ptr_message   A pointer to the processed message
Returns:
TRUE if the message was processed 
   #include <cywin.h>
     ...
     struct cDialog dialog;
     struct module_t main_module;
     struct Message* ptr_message;
     ...
     init_module( &main_module );
     ...
     cDialog_ctor( &dialog, NULL, str_Really_exit,
                     mbQuit | mbCancel | mbs1, 0, main_module.m_process );
     ...
     cDialog_Show( &dialog );
     ...
     ptr_message = cWinApp_get_message( main_module.m_process, 0, 1, MSG_USER );
     if( cDialog_proc( &dialog, ptr_message ) && dialog.ModalResult != mrNone )
     {
       if( dialog.ModalResult == mrQuit )
       {
         ...
       }
     }
     ...
     cDialog_dtor( &dialog, LEAVE_MEMORY );

void cDialog_update ( struct cDialog * ptr_dialog )
 

Updates a cDialog object.

Parameters:
ptr_dialog   A pointer to the initialized cDialog object
Returns:
None