PowerBASIC Information Center Tutorials
These tutorials were written to help you get a quick, but thorough, understanding of PowerBASIC -
the scope of the language as well as it's specific capabilities.
PowerBASIC supports a variety of functions which generally get/set
information from Windows (clipboard, desktop, memory, etc.) or from
the application itself. These can be broken into the following
Get Text, Set Text, Get Item,
Set Item, Reset
Get Client, Get Loc, Get Size
Get ID, Get Parent
peek, peek$, poke, poke$
alloc, free, lock, size, unlock
System Call Function Summary
Here's a one-line description of each of the functions.
- CLIPBOARD - get/set clipboard content (text and images)
- command$ - get program command-line arguments
- DESKTOP - get desktop size, client size, client top/left coordinates
- environ/environ$ - set/return environment values
- EXE - get application name/path
- GLOBALMEM - Allocate or release global memory
- peek/peek$ - get byte(s) at memory location
- poke/poke$ - store byte(s) at memory location
- shell - run external program w/option to wait until program completes
- WINDOW - get parent/id of any window in application
System Call Function Reference
Here's a quick reference of the available functions, in alphabetical
CLIPBOARD Set Text "mystring" TO iSuccess&
CLIPBOARD Get Text TO RetreivedText$
CLIPBOARD Set Item cbFormat, hItem TO iSuccess&
CLIPBOARD Get Item cbFormat TO hReturn&
CLIPBOARD RESET TO iSuccess ' delete clipboard content
iSuccess&: 0=false, -1=success
hItem is handle of item sent to clipboard
hReturn is handle of item received from clipboard
cbFormats (clipboard formats):
%CF_BITMAP - bitmap handle (HBITMAP)
%CF_DIB - memory object (BITMAPINFO structure and bitmap bits)
%CF_DIF - Software Arts' Data Interchange Format
%CF_ENHMETAFILE - enhanced metafile handle (HENHMETAFILE)
%CF_HDROP - HDROP handle (list of files)
%CF_LOCALE - locale identifier handle
%CF_METAFILEPICT - metafile picture handle (METAFILEPICT)
%CF_OEMTEXT - OEM text characters (CRLF EOL, Null EOF)
%CF_PALETTE - color palette handle
%CF_PENDATA - MS Pen Computing data
%CF_RIFF - RIFF audio data
%CF_SYLK - MS Symbolic Link (SYLK) format
%CF_TEXT - Text (CRLF EOL, Null EOF)
%CF_TIFF - TIF file
%CF_UNICODETEXT - Unicode text (CRLF EOL, Null EOF)
%CF_WAVE - WAV audio data
Clipboard holds only one type of data at a time. If you Set the clipboard,
previous data is lost.
With Get Item, hReturn& is the handle to the item retrieved.
result$ = command$ ' entire command-line
result$ = command$(n%) ' nth command-line argument, 0=all
Assumes arguments are space delimited. If n% is too large, "" is returned.
The IDE allows specification of a command-line string for testing purposes.
- DESKTOP GET Client/Size/Loc
DESKTOP Get Client TO Width&, Height& 'client height width
DESKTOP Get Size TO Width&, Height& 'entire desktop size
DESKTOP Get Loc TO x&, y& 'top/left corner
Client area does not include taskbar. Client top/left is normally 0,0
but if taskbar is moved to top or left side of screen, then the client
top/left changes accordingly.
ENVIRON "name=value" 'use string name/value pairs to set values
ENVIRON "name=" 'name only (no value) removes from table
ENVIRON "temp=c:\temp" 'set "temp" environ value
ENVIRON "path=c:\" 'don't try this! just an example.
result$ = environ$("path") 'get path value from environment
result$ = environ$("temp") 'get "temp" value from environment
result$ = environ$(12) 'get 12th environment table entry
When an app starts, it is given a copy of the system environment table.
PowerBASIC functions work with the copy. When the program ends, the
system environment table is unchanged.
Assume this is run: "c:\data\fixit.exe"
result$ = EXE.extn$ ' ".exe"
result$ = EXE.full$ ' "c:\data\fixit.exe"
result$ = EXE.name$ ' "fixit"
result$ = EXE.namex$ ' "fixit.exe"
result$ = EXE.path$ ' "c:\data\"
If this code is in a DLL, the information returned is that of the
EXE which loaded the DLL.
- GLOBALMEM alloc/free/lock/size
GLOBALMEN alloc count TO vHandle
GLOBALMEN free mHandle TO vHandle
GLOBALMEN lock mHandle TO vPointer
GLOBALMEN size mHandle TO vSize
GLOBALMEN unlock mHandle TO vLocked
Dim address As DWord ' 32 bit address (4 bytes)
NumVar = PEEK, address 'assign 1 byte to numeric variable
NumVar = PEEK BYTE, address 'read/convert # bytes corresponding
'to specified data type
'can use byte, word, dword,
'integer, long, quad,
'single, double, ext, cur, cux
n% = PEEK Integer, address
n! = PEEK Single, address
StringVariable = PEEK ASCIIZ, address, ByteCount
s$ = PEEK$ address, 5 'get 5 characters, put into s$
Dim s as ASCIIZ
s = PEEK$ ASCIIZ address, 5 'get 5 characters, insert &Nul at end
Use peek to get a single byte, and peek$ to return a sequence of bytes.
Dim address As DWord ' 32 bit address (4 bytes)
poke address, i% ' put value of i% at 1-byte address
poke BYTE, address, i% ' put # bytes corresponding to specified
' data type, starting at address
' can use byte, word, dword,
' integer, long, quad, single,
' double, ext, cur, cux
poke$ String, address, "hello" ' fixed-length or dynamic string
poke$ ASCIIZ, address, "hello" ' ASCIIZ string
poke$ Field, address, "hello" ' Field string
Use poke for numeric data, and poke$ for string data. These are
generally used for speed-critical sections of a program, or to
access memory (such as video memory) that otherwise would not be
accessible using standard PowerBASIC functions.
Poke$ will write all characters found in the string being written.
The application must control the location and length of written data to
ensure that the written data does not write into areas which can corrupt
other data or create a GPF.
pID& = SHELL("notepad.exe",1) 'run notepad and keep going
pID& = SHELL("cmd /c dir*.*") 'open DOS, run "dir *.*", end
pID& = SHELL("cmd /k dir*.*") 'open DOS, run "dir *.*", not end
pID& is the child process ID.
0 - hide window
1 - normal w/focus (default)
2 - minimized w/focus
3 - maximized w/focus
4 - normal w/o focus
5 - minimized w/o focus
Runs another app without waiting for it to stop. ERR contains
information on success/failure.
Option available for child process to inherit file handles of
current process. See PowerBASIC Help for more information.
For more info on using the DOS CMD command, open a DOS window and
enter "cmd /?". This gives a listing of all cmd options.
Paths searched for program to execute: program directory, default directory,
\windows\system32, \windows\system16, \windows, and PATH.
- WINDOW GET ID
WINDOW Get ID hWin TO ID& ' hWin - handle of window
WINDOW Get Parent hWin TO hParent&
Works on control or dialog. ID& = control ID (or 0 if hWin is a dialog).
If you have any suggestions or corrections, please let me know.