ProgressBar Control
The progressbar control is simply a rectangle which can be filled
with color to indicate progress on a task. It can be vertical
or horizontal.
- Syntax:
Control Add ProgressBar, hDlg, id&, txt$, x, y, xx, yy, _
style&, extsytle& CALL callback
- Source Code Example:
This short example creates a complete application with a single progressbar.
Progressbars do not receive messages, so no Callback function code is
provided.
This tutorial page discusses most of the statements used, however the
DDT,
Controls,
Messages, and
Callback tutorials provide
background information that may be helpful in understanding the example.
#Compile Exe
Global hDlg As Dword
Function PBMain() As Long
Dialog New Pixels, 0, "ProgressBar Test",300,300,200,200, _
%WS_SysMenu, 0 To hDlg
Control Add Progressbar, hDlg, 100,"", 50,50,100,20
Progressbar Set Pos hdlg, 100, 80
Control Set Color hdlg, 100, %Red, %Blue
Dialog Show Modal hDlg
End Function
In this example, the progress bar is 80% complete and the fg/bg colors
are set to red and blue.
An additional example of a callback function is provided further down this page.
- Visual Examples:
And here are a few examples of what you can do with the progressbar control in PowerBASIC.
Variations on the Control Add ProgressBar statement were used to create the examples.
In some cases, other Control statements were used to modify the results.
As you can see, there's really not much you can do with a progressbar - change the orientation, change the colors and set the type of
fill use (smooth or segmented).
Arguments
The Control Add statement is used to create all new controls. Here are the
statement's arguments and any special significance to the progressbar control.
- hDlg
The dialog handle to which the progressbar control is to be added. The value was returned
by the DIALOG NEW statement.
- id&
The id& argument is a control identifier assigned by the programmer.
It must be a value of 1-65535. Values of 100+ are suggested, as PowerBASIC
pre-assigns identifiers with special meaning. Numeric equates are
suggested over the use of literal values.
- txt&
An ampersand can also be included in txt$, such as "&Stop", to specify a hot key Alt-S.
But since a progressbar control cannot get focus, using the hotkey will give focus to the
next control in the tab order.
The progressbar control does not display text, so the txt$ argument is usually set
to "". However, any entered txt$ value can be accessed using the
GET/SET TEXT statements. This provides the application with a
control-specific property that can used for any purpose.
- x,y and xx,yy
The integer x,y and xx,yy dimensions use the same units as the parent dialog.
(x,y) is the upper/left coordinates of the control. (xx,yy) is the width/height
of the control.
- style& and extstyle&
The style& and extstyle& arguments (listed below) are optional. If not supplied, default
values are used (see the table below). If values are supplied, they completely replace
default values (i.e., the entered values are not in addition to the default values).
- CALL
The "CALL callback" section is optional. If not supplied, the callback
function of the parent dialog is used. An example callback function for
progressbar controls is provided further down this page. The #MESSAGE COMMAND compiler
directive can be used to prevent sending %WS_NOTIFY messages to the callback
function. By default, both %WS_NOTIFY and %WS_COMMAND messages are sent.
Usage
The default step increment is 10 and the default range is 1-100.
ProgressBar-Specific PowerBASIC Statements
PowerBASIC provides several statements specific to the
progressbar control. These allow getting/setting progressbar
properties.
| ProgressBar Get POS
| get current position
|
| hDlg, id&, TO value&
|
| 
|
| ProgressBar Get Range
| get upper/lower values of range
|
| hDlg, id& TO LoValue&, HiValue&
|
|
|
| ProgressBar Set POS
| set position
|
| hDlg, id&, pos&
|
|
|
| ProgressBar Set Range
| set upper/lower values of range
|
| hDlg, id&, LoValue&, HiValue&
|
|
|
| ProgressBar Set Step
| set default increment value
|
| hDlg, id& TO step&
|
|
|
| ProgressBar Step
| increment position (by default value if increment& omitted)
|
| hDlg, id&, increment&
|
|
|
See the Usage section above for information on how to use the
values made available by these statements.
Messages, Notifications, Styles, and ExtSstyles
There are four types of named constants in the following table.
All are pulled from the
MSDN web site.
- Notifications - event notifications a control receives
- Messages - controls may send these
- Styles - affect the visual look of a control
- ExtStyles - additional values that affect the visual look
The first column contains control-specific named constants and the
second column contains generic window named constants (progressbar
controls are windows).
Also, if the PowerBASIC Help file has an entry on the value, it is
highlighted in yellow. If the value was noted in PowerBASIC Help as
a default value, it is also shown in bold text.
In the values for notifications, descriptions starting with -n and
-c refer to events received through the %wm_notify and %wm_command
messages. By default, PowerBASIC controls can receive both of these
messages.
And here is a short description of many of the named constants
corresponding to notifications, styles, and extstyle - particularly
those discussed in the PowerBASIC Help topics.
%pbs_smooth - smooth, not segmented, display
%pbs_vertical - vertical advance
%ws_border - use thin line border
%ws_ex_clientedge - apply sunken edge border
%ws_ex_staticedge - apply 3D border
%ws_ex_windowedge - apply raised edge border
Callback Function
A progressbar control does not send messages and does require/support
a callback function.
Issues
The Help section says %ws_border is the default style&, but it is not
shown in the list of style& options.
A default extstyle& is not specified in Help
I'll update with more information as it becomes available.
CONTROL Statement Syntax
The following table lists the various Control statements (except the ADD statements).
Most, but not all, can be used with the progressbar control. A one-line description of
the statement and then its syntax are presented.
| CONTROL DISABLE | disable
|
| hDlg, id&
|
|
|
| CONTROL ENABLE | enable
| hDlg, id&
| |
| | CONTROL GET CHECK | check state
| hDlg, id& TO iResult1&
| |
| | CONTROL GET CLIENT | top/left location
| hDlg, id& TO wide&, high&
| |
| | CONTROL GET LOC | top/left location
| hDlg, id& TO x&, y&
| |
| | CONTROL GET SIZE | width/height
| hDlg, id& TO width&, height&
| |
| | CONTROL GET TEXT | text
| hDlg, id& TO txt$
| |
| | CONTROL GET USER | get user data
| hDlg, id&, index& TO retvar&
| |
| | CONTROL HANDLE | window handle for control id
| hDlg, id& TO hCtl&
| |
| | CONTROL KILL | remove control
| hDlg, id&
| |
| | CONTROL POST | put message in queue (non-blocking)
| hDlg, id&, Msg&, wParam&, lParam&
| |
| | CONTROL REDRAW | schedule redraw of control
| hDlg, id&
| |
| | CONTROL SEND | send message to control, wait for processing
| hDlg, id&, Msg&, wParam&, lParam& TO iResult2&
| |
| | CONTROL SET CHECK | set check for 3state or checkbox
| hDlg, id&, checkstate&
| |
| | CONTROL SET CLIENT | change size to specific client area size
| hDlg, id&, wide&, high&
| |
| | CONTROL SET COLOR | set fg/bg color
| hDlg, id&, fgcolor&, bgcolor&
| |
| | CONTROL SET FOCUS | set focus
| hDlg, id&
| |
| | CONTROL SET FONT | select font for a control
| hDlg, id&, fonthandle&
| |
| | CONTROL SET LOC | relocate control within dialog
| hDlg, id&, x&, y&
| |
| | CONTROL SET OPTION | set check state of option control
| hDlg, id&, minid&, maxid&
| |
| | CONTROL SET SIZE | change control size
| hDlg, id&, width&, height&
| |
| | CONTROL SET TEXT | change control text
| hDlg, id&, text$
| |
| | CONTROL SET USER | set user data
| hDlg, id&, index&, uservalue&
| |
| | CONTROL SHOW STATE | toggle visibility
| hDlg, id&, showstate& TO iResult3&
| |
| | | | | | | | | | | | | | | | | | | | | | | |
If you have any suggestions or corrections, please let me know.