eCo Software Developer Connection


About DevCon
Subscription to DevCon
Budget of DevCon
FAQ


Roadmap
eCo Software runtime
eCo Software toolkit
Contacts

This is an old revision of the document!


Progress bar

Name Description Download
Progress bar Progress bars allow users to follow the progress of a lengthy operation.
eCo Software toolkit

There are three kinds of Progress bar:

Eye-candy, round
Eye-candy, linear
Standard

In PROGRESS.DLL version 2.0 PrgShowDlg() function changed. New features were added, but backwards compatibility was preserved, so additional parameters are optional. Here is new syntax:

HWND APIENTRY PrgShowDlg(HWND hwndParent,      // Progress dialog parent window
                         HWND hwndOwner,       // Progress dialog owner window
                         USHORT fsFlags,       // Flags to specify properties 
                                               // of the Progress   Dialog. 
                                               // PRS_* constants are to be used.
                         HMODULE hmodResource, // Module handle of the resource 
                                               // file. Use -1 for PROGRESS.DLL, 
                                               // 0 - for executable, 
                                               // other - module handle, obtained 
                                               // with DosLoadModule call.
                         ULONG ulIcon,         // Resource ID of the PNG 
                                               // sequence in the hmodResource. 
                                               // For PROGRESS.DLL ID_PROGRESS_PNG_ICON* 
                                               // constants to be used. Ignored if 
                                               // PRS_ICON flag is not set.
                         ULONG ulBar,          // Resource ID of the pair of PNG images 
                                               // in the hmodRsource. For PROGRESS.DLL 
                                               // ID_PROGRESS_PNG_BAR constant to be used. 
                                               // Ignored if PRS_BAR and PRG_IMAGE flags 
                                               // are not set.
                         USHORT usId,          // Progress Bar dialog control ID. Used 
                                               // to recognize Progress Dialog among 
                                               // other controls and to determine command 
                                               // value of WM_COMMAND message sent by 
                                               // Progress Dialog to its owner, when 
                                               // user tries to interrupt a process.
                         PSZ pszTitle,         // Title of the dialog control. If NULL, 
                                               // progress dialog window have no 
                                               // titlebar and no frame.
                         PSZ pszButton1,       // Caption on the button to allow user 
                                               // to interrupt process. If NULL no button 
                                               // apperas in the dialog and process cannot 
                                               // be interrupted.
                         PSZ pszCaption1,      // The first (topmost) caption in the 
                                               // dialog. Could be NULL, if the caption 
                                               // is unused
                         PSZ pszCaption2,      // The second caption in the dialog. Could 
                                               // be NULL, if the caption is unused
                         PSZ pszCaption3,      // The third caption in the dialog. 
                                               // Could be NULL, if the caption is 
                                               // unused. If this caption is too 
                                               // long it will be broken into several lines.
                        [PSZ pszButon2[ ,      // Button 2 caption. Significant 
                                               // only when PRS_BUT_2 flag is specified.
                         PSZ pszButton3[ ,     // Button 3 caption. Significant only when 
                                               // PRS_BUT_3 flag is specified.
                         PSZ pszButtonHelp[ ,  // Help Button caption. Significant 
                                               // only when PRS_BUT_HELP flag is specified.
                         LANGE hLange]]]]);    // LANGE handle. Significant only 
                                               // when PRS_OWNLANGE flag is specified.

As you can see, in version 2.0 progress dialog can contain up to 3 action buttons and one help button, Just specify appropriate PRS_BUT_* flag and button caption parameter. You can also specify LANGE handle to let PROGRESS.DLL automatically translate all captions using LANGE library.

Another additional flag is PRS_DISMISS. If this flag is set, progress bar dialog will be automatically dismissed, when any action button (not help button) is clicked. Otherwise, dialog will not be dismissed, WM_COMMAND message will be posted to the dialog's owner instead.

Q: When to use Progress bar?

Open the window with progress bar if operation requires more than 5-10 seconds. You should provide Cancel button to user.

Q: Why to use our Progress bar?

  • we draw eye-candy progress bar
  • we are sorting text strings on the surface of the window
  • we calculate the size of the window

Q: Which kind of Progress bar to use?

Use Round PBar for applications which are rebuilding / changing / destroying something. Don't use Round PBar for copy / search operations.

Notes:

  • Modal PBar - use WinProcessDlg() and WinSetSysModalWindow(). If WinProcessDlg() was called, use WinDismisssDlg() to stop it. Don't remove modal PBar window using WinDestroyWindow() before call of WinDismisssDlg()! Don't try to open new windows (Message Boxes) while modal window is floating.
  • If you want make additional initialization of PBar after creation (for example, you are going change attributes for some controls), don't set PRS_SHOW flag. Call WinShowWindow() after additional initialization to show the PBar.
  • To use own resources put them to EXE or DLL. Pictures should have type RT_PNG (defined in “progress.h”), IDs of the resources should follow in succession. The ID of the first picture should be passed to PrgShowDlg().
  • If you are going change a text string during the process then pass in during initialization as long text string full of spaces. Use PrgSetupCaption() to update the text string, flUpdate = FALSE.
  • Read examples (prtest.c) before usage of PROGRESS.DLL in your application.

Notes 2: Useful hints and advices

(Progress-bar, Message box)

  • First of all, examine carefuly “Progress Bar Test Window” sample program (prtest.exe), too see, how PROGRESS.DLL should be used, and how it works.
  • MSG-BOX-1: It's a good idea to use your own captions on the buttons instead of the default. Always use verbs as captions: “Close window”, “Do not close”, “Overwrite file”, “Keep file” instead of “Yes”, “No”, “OK”, etc.
 
en/progress_bar.1256387600.txt.gz · Last modified: 2009/10/24 11:33 (external edit)

 
Recent changes RSS feed
© 2001 - 2009 eCo Software, All rights reserved