PPSR > Plug-ins 
- Overview
- Plugins extend the functionality of PowerPro, offer interfaces to other programs/languages, & do groovy things.
- There are 2 types of plugins:
- Plugins by Bruce Switzer that come preinstalled in PowerPro:
- Clip
- Date
- Event
- File
- Float
- Int64
- Map
- Note
- Vec
- Win
- All other plugins.
- The Plugins
Au & AutoItDLL- Author
- Jonathan Bennett wrote the AutoItDLL plugin, and ??? wrote the Au plugin for PowerPro.
- See Also
- AutoItDLL plugin reference
- path\to\PowerPro\plugins\AutoItDLL.chm
- Au plugin notes
- path\to\PowerPro\plugins\au.txt
- Clip
- Author
- Overview
- The clip plugin lets you manipulate text of any length on the clipboard.
- Commands
- Append
- Description
- Appends text to the clipboard.
- Syntax
- Parameters
- txt
- (string) the text to append
- Examples
- Clip.Append("\r"++shortdate)
- Adds a newline & the date to whatever else is currently on the clipboard.
- Clear
- Description
- Syntax
- Examples
- Copy
- Description
- Copies selected text in active window to clipboard.
- Syntax
- Examples
- Cut
- Description
- Cuts selected text in active window to clipboard.
- Syntax
- Examples
- FromFile
- Description
- Copies the contents of the specified file to the clipboard.
- Syntax
- Parameters
- fname
- (string) full path to the file
- Examples
- Clip.FromFile(?"c:\dev\lang\test.txt")
- Copies the contents of the file "test.txt" located at c:\dev\lang\test.txt to the clipboard.
- FromFileAppend
- Description
- Appends file to clipboard.
- Syntax
- Clip.FromFileAppend(fname)
- Parameters
- fname
- (string) full path to the file
- Examples
- Clip.FromFileAppend(?"c:\program files\somepgm\myfile.txt")
- Notes
- Does not support rich text format.
- Get
- Description
- Retrieves the text on the clipboard.
- Syntax
- Return Value
- (string) text from the clipboard
- Examples
- Notes
- "Clip.Get" is similar to the built-in function "clip", except that while clip returns just the first line of the clipboard, Clip.Get returns the whole clipboard contents.
- IgnoreNext
- Description
- Next item added to clipboard will not be captured by PowerPro clip capture.
- Syntax
- Examples
- Length
- Description
- Retrieves the length of the clipboard contents.
- Syntax
- Return Value
- (integer) number of characters on the clipboard
- Examples
- if (Clip.Length > 60)
messagebox("okcancel warning", "Too long!", "Error")
- Shows a warning message if data just copied has more than 60 characters.
- Paste
- Description
- Paste the contents of the clipboard to the active window.
- Syntax
- Examples
- Clip.FromFile(?"c:\my docs\signature.txt")
Clip.Paste
- Puts the contents of the file "c:\my docs\signature.txt" onto the clipboard, then pastes it into the active window.
- Set
- Description
- Sets the clipboard with specified text.
- Syntax
- Parameters
- txt
- (string) the text to set clipboard with
- capture
- (bool) whether PowerPro should capture the clip
- Possible values
- 1
- this clip will be captured by PowerPro
- 0
- this clip will not be captured by PowerPro
- Optional, default is 0.
- Examples
- Win.Debug(Clip.Get)
Clip.Set("quick brown fox")
Win.Debug(Clip.Get)
- Outputs the current clipboard contents, then sets the clipboard with the text "quick brown fox" & outputs that.
- Clip.Set("quick brown fox", 1)
- Sets the clipboard with the text "quick brown fox", also storing this text with other captured PowerPro clips.
- Notes
- PowerPro stores clips in the directory "clip" under your PowerPro installation folder. The number of clips stored is configurable in the GUI Control tab of the PPCD.
- SetPaste
- Description
- Sets the clipboard with specified text, then sends a Ctrl-V command to paste it to foreground window.
- Syntax
- Parameters
- txt
- (string) the text to set & paste
- Examples
- Clip.SetPaste("quick brown fox")
- Sets clipboard with "quick brown fox", then pastes it to the active window.
- ToFile
- Description
- Puts the contents of the clipboard into the specified file.
- Syntax
- Parameters
- fname
- (string) filename including path
- NoErr
- (bool) whether to show any error messages
- Optional, default is 0 (error messages are shown).
- Possible Values
- Examples
- Clip.ToFile(?"c:\docs\important.txt",1)
- Puts clipboard contents into the file "c:\docs\important.txt", hiding any error messages.
- Clip.ToFile(?"c:\docs\important.txt")
- Puts clipboard contents into the file "c:\docs\important.txt", showing any error messages.
- ToFileAppend
- Description
- Appends the contents of the clipboard to file fname.
- Syntax
- Clip.ToFileAppend(fname,NoErr)
- Parameters
- fname
- (string) filename including path
- NoErr
- (bool) whether to show errors
- Possible Values
- Optional, default is 0 (show any errors).
- Examples
- Clip.ToFileAppend(?"c:\docs\stuff.txt", 1)
- Adds the clipboard's contents to the file, "c:\docs\stuff.txt", hiding any error message if an error occurs.
- Clip.ToFileAppend(?"c:\docs\stuff.txt")
- Adds the clipboard's contents to the file, "c:\docs\stuff.txt", & shows any error message if an error occurs.
- Notes
- Clip.ToFileAppend does not support rich text format.
- Write
- Description
- Turns off writing of clips to memory.
- Syntax
- Parameters
- toggleWord
- Possible Values
- "off"
the only allowable value?
- Examples
- Notes
- See Also
- PPSR > Built-in Commands > Clip
- Date
- Author
- Overview
- The Date plugin lets you work with Date values.
- Commands
- AddDays
- Description
- Adds the specified number of days to a date & returns the result.
- Syntax
- Date.AddDays(start, days)
- Parameters
- start
- (integer) starting date, in format: yyyymmdd
- days
- (integer) number of days to add to start_date
- Return Value
- (integer) resultant date, in format "yyyymmdd"
- Examples
- local d2 = Date.AddDays(20021031, 2)
- Sets local variable d2 to 20021102.
- Win.Debug(Date.AddDays (20021031, -365))
- Outputs "20011031" to a debug window.
- if (select(date, 5, 6) != select(Date.AddDays(date, 1), 5, 6))
Win.Debug("Today is the last day of the month")
- Tests if today is the last day of the the month & outputs a message if so.
- Win.Keys(formatdate("d/M/yyy",Date.AddDays(date,-1)))
- Types yesterday's date in format given.
- Get
- Description
- Displays a calendar and returns the selected date, or 0 if Cancel button (or <Esc> key) is pressed.
- Syntax
- Return Value
- (integer) the selected date, in format: yyyymmdd
- Examples
- Win.Debug(Date.Get)
- Shows a PowerPro calendar dialog, then outputs the selected date to a debug window.
- Sub
- Description
- Calculates the number of days between 2 dates.
- Syntax
- Parameters
- start
- minus
- (integer) second date, which is subtracted from d1
- Return Value
- (integer) the number of days
- Examples
- Win.Debug( Date.Sub(20021102, 20021031) )
- Sets local variable "days" to 2.
- Win.Debug( Date.Sub(20021031, 20021102) )
- Sets local variable "days" to -2.
- Today
- Description
- Today's date.
- Equivalent to the PowerPro keyword date.
- Syntax
- Return Value
- (integer) today's date, in format: yyyymmdd
- Examples
- Win.Debug(Date.Today)
- Outputs today's date to a debug window.
- WeekDay
- Description
- Returns the day of the week the specified date falls on, as a number from 0-6, where 0=Sunday.
- Syntax
- Parameters
- date_val
- (integer) target date, in format: yyyymmdd
- Return Value
- (integer) number from 0 to 6, representing the day of the week date_val falls on
- Examples
- local d1 = Date.WeekDay(20021029)
- Sets local variable d1 to 2 (Tuesday).
- WeekNum
- Description
- Returns the week number the specified date falls in.
- Syntax
- Parameters
- Return Value
- Examples
- Win.Debug(Date.WeekNum(20020110))
- Win.Debug(Date.WeekNum(20021029))
- Notes
- The week number definition follows the ISO standard, where Week 1 of any year is:
- the week that contains 4 January
- the week that contains the first Thursday in January
- YearDay
- Description
- Returns the day of the year the specified date is.
- Syntax
- Parameters
- Return Value
- Examples
- Win.Debug(Date.YearDay(20021029))
- Win.Debug(Date.YearDay(20031029))
- Notes
- Dates processed by the date plugin follow the same format as the dates produced by PowerPro keywords and functions like date and formatdate().
- Dates are represented as eight digit number yyyymmdd, such as 20021028 for October 28, 2002, or 20030101 for January 1, 2003.
- DLL
- Author
- Alan Campbell aka entropyreduction
- Event
- Author
- Overview
- The event plugin lets you create & work with events: commands configured to execute at specified times, intervals, with n repeats, and/or only when a particular condition is true.
- Commands
- Count
- Description
- Returns the number of intervals remaining for an event scheduled with a count.
- Syntax
- Parameters
- e
- (string) the event, must have a count set.
- Examples
- Global myEvt = Event.Create(2, 3, ?%Win.Debug("Iterations left: "++Event.Count(Event.This))%)
- CountThis
- Description
- Returns the number of intervals remaining for an event with a count, called from within the event's assigned command.
- Syntax
- Examples
- ; output "10, ..., 1" in the debug window.
Event.Create(1,10,"Win.Debug(Event.CountThis)")
- Event.Create(2, 3, ?%Win.Debug("Iterations left: "++Event.CountThis)%)
- Notes
- Must be used in the command assigned to an event when it is created, & never as a standalone function.
- Create
- Description
- Creates a new event and returns its handle.
- Syntax
- e = Event.Create(s,c,cmd,expr)
- Parameters
- s
- (integer) number of seconds between event repeats
- c
- (integer) count
- Possible Values
- 0
- event continues until removed by an Event.Destroy(e) call
- c>0
- after c occurrences, the event is removed
- cmd
- (string) command to be executed after each interval
- If expr is specified, cmd only executes when expr is true.
- May contain multiple separate commands itself using the \r symbol. See Special Symbols
- expr
- (string) expression that is evaluated after each interval to determine whether the cmd parameter is executed
- Optional
- Values
- eval(expr) == 0 || eval(expr) == ""
- do not execute cmd parameter
- eval(expr) == any other result
- expr omitted
- cmd parameter is always executed
- Return Value
- Examples
- ; create an event which debugs the variable testvar once every 3 seconds, continuing indefinitely
e = Event.Create(3,0,"Win.Debug(testvar)")
- ; create an event to check for a visible notepad window, send key "abc" to it, then end,
; continuing until either notepad appears, or 20 seconds elapses
e = Event.Create(2,10, ?%Win.Keys("abc")\r Event.DestroyThis%, ?%visiblewindow("*notepad*")%)
- Special Symbols
- \r
- Separates multiple commands within the cmd parameter
- e.g.
- event.create(3,0,"win.debug(var)\r if (shift)\r event.destroythis")
- \+
- Splits the function call over two lines
- e.g.
- e=event.create(2,10,"keys abc\r event.destroythis", \+
?=visiblewindow("*notepad*")=)
- Notes
- If you specify both c & expr, c is decremented whether or not cmd is executed; this way, c can act as a watchdog to end the event in case expr never evaluates to true.
- CreateMS
- Description
- Creates a new event and returns its handle.
- Similar to Event.Create(), except that the interval is specified in milliseconds.
- Syntax
- e = Event.CreateMS(m,c,cmd,expr)
- Parameters
- m
- (integer) number of milliseconds between event repeats
- Minimum is 20 milliseconds
- c
- (integer) count
- Values
- 0
- event continues until removed by an Event.Destroy(e) call
- c>0
- after c occurrences, the event is removed
- cmd
- (string) command to be executed after each interval
- If expr is specified, cmd only executes when expr is true.
- May contain multiple separate commands itself using the \r symbol. See Special Symbols
- expr
- (string) expression that is evaluated after each interval to determine whether the cmd parameter is executed
- Optional
- Values
- eval(expr) == 0 || eval(expr) == ""
- do not execute cmd parameter
- eval(expr) == any other result
- expr omitted
- cmd parameter is always executed
- Examples
- ; create an event which debugs the variable testvar once every 100 milliseconds, 20 times
e = event.create(100,20,"win.debug(testvar)")
- Special Symbols
- \r
- Separates multiple commands within the cmd parameter
- e.g.
- Event.Create(3,0,"win.debug(var)\r if (shift)\r event.destroythis")
- \+
- Splits the function call over two lines
- e.g.
- e = Event.Create(2,10,?%Win.Keys("abc")\r Event.DestroyThis%, \+
?%visiblewindow("*notepad*")%)
- Notes
- Note that the number of milliseconds must be equal or greater than 20.
- As with Event.CreateMS(), if you specify both c & expr, c is decremented whether expr is true or false; this way, c can act as a watchdog, to end the event in case expr never evaluates to true.
- Destroy
- Description
- Removes specified event & returns 0.
- Syntax
- Parameters
- Return Value
- 0
- This can be assigned to a variable (such as the event handle) to indicate the event is not running.
- Examples
- ; destroy event e & assign e the value 0
e = Event.Destroy(e)
- DestroyAll
- Description
- Removes all active events.
- Syntax
- Return Value
- 0
- This can be assigned to a variable (such as the event handle) to indicate the event is not running.
- Examples
- Local new_evt = Event.Create(2,3,?%Win.Debug("new_evt = "++Event.Exists(new_evt))%)
Event.DestroyAll
Win.Debug("new_evt = "++Event.Exists(new_evt))
- DestroyThis
- Description
- Removes current event & returns 0.
- Syntax
- Return Value
- 0
- This can be assigned to a variable (such as the event handle) to indicate the event is not running.
- Examples
- e = Event.Create(2, 5, \+
"Win.Keys(\"abc\") \r e = Event.DestroyThis", \+
"visiblewindow(\"=notepad\")")
- Sets up an event to check for notepad every 2 seconds, up to 5 times, & if found, sends keys "abc" then destroys itself.
- Note that the command string is only double-delimited until just before the first "\r", and the rest of the string is only in one set of double quotes.
This is because the "\r" will not be recognised if double-delimited -- ?%% syntax strings do
- Notes
- Can only be called within an event command, as set at event creation, & not as a standalone command.
- Exists
- Description
- Checks if an event exists.
- Syntax
- Parameters
- Return Value
- Examples
- Win.Debug("does e exist? " ++ Event.Exists(e))
- Message
- Description
- Creates a message box with specified title & message, which counts down once per second, starting at count.
- Syntax
- Event.Message(count,cmd,message,title[,ontop[,left,top]])
- Parameters
- count
- (integer) initial value of counter
- cmd
- (string) cmd to execute if either count gets to zero, or the "Start Now" button is pressed
- Optional
- message
- (string) message to appear in message box
- Optional, message box has no message if omitted.
- title
- (string) title of message box
- Optional, defaults to "Waiting for...".
- ontop
- (boolean) sets topmost value of message box
- Values
- 1
- 0
- message box is not topmost
- left
- Left coordinate of message box.
- Optional, not considered unless the next parameter, top, is also supplied.
- Default is for message box to be centered on screen.
- top
- Top coordinate of message box.
- Optional, if not supplied, message box is centered on screen.
- Return Value
- (integer) the event handle
- Global Variables
- _exit_
- set to either:
- 1
- 0
- if "Start Now" is pressed
- Examples
- local e = Event.Message(10, ?%Win.Message("Opening Notepad...", "Info")%, ;;+
"Click Start Now to jump straight to it", "Waiting...", 1)
- Notes
- Message box is centered unless both left and top are supplied.
- This
- Description
- Refers to the event handle.
- Syntax
- Examples
- e = Event.Create(1,20,".myscript(Event.This)", ?%visiblewindow("=winword")%)
- Create event to call script file "myscript" when MS word has a visible window,passing the event handle as an argument. Event will run at most 20 seconds.
- Global myEvt = Event.Create(2, 3, ?%Win.Debug("Iterations left: "++Event.Count(Event.This))%)
- Notes
- Can only be used in the command assigned to an event when it is created, & not as a standalone command.
- Notes
- The event plugin is a more flexible alternative to the Wait command and to timers.
- The event plugin can support at most 50 simultaneously active events.
- Only global variables can be used in the expression and commands used in an event; you cannot use local or static variables.
- File
- Author
- Overview
- The File plugin lets you work with files & folders.
- Commands
- Alpha-order
- A - P
- AllDrives
- Description
- Outputs a multi-line string with one line for each valid drive.
- Syntax
- Return Value
- (string) multi-line string with one line per valid drive. Use line function to work with each drive.
- Examples
- Win.Debug(File.AllDrives)
- Would output something like the following to a PowerPro debug window:
A:\
C:\
D:\
E:\
F:\
*Note that the PowerPro Debug window shows line breaks within a string as something like "▍" and keeps the whole multi-line string on the one debug line.
- Local sDrives, i
sDrives = File.AllDrives
for (i=1; i<line(sDrives,0)+1; i=i+1)
Win.Debug(i,"=",line(sDrives,i))
endfor
- Puts the list of all system drives into variable "sDrives", then loops through the list, outputting the count & the drive name for each line.
- AllFiles
- Description
- Cycles through all files in the given filepath (and, optionally, its subfolders), either counting them, or running a command on each one.
- Syntax
- File.AllFiles(path, command, subfoldersflag, pumpflug, hidden)
- Parameters
- path
- (string) path to the folder with the files and/or subfolders to be processed
- Possible Values
- folder path
- subfolders may be processed, depending on parameter subfoldersflag
- folder path with wilcards
- subfolders are not processed
- command
- (string) the command to run
- The command parameter may be omitted or set to "", in which case the File.AllFiles call simply returns a count of all files in the specified path.
- Special Variables
- _file_
- [global variable] set to each file name and can be used in the command
- |
- replaced by the file being processed each time the command is run
- subfoldersflag
- (integer) sets whether subfolders will be processed
- Optional, default is 0.
- Possible Values
- 0
- only the files in the selected folder are processed (default)
- 1
- the command is run on files in selected folder & all subfolders
- 2
- the command is run on the folder names directly, & files in subfolders are not processed
- pumpflag
- (integer) keeps PowerPro responsive while files are being processed by checking for user input every n files, where n = value of pumpflag.
- Optional, default is 0.
- Possible Values
- n>0
- every n files, PowerPro checks for user input to process (e.g. from a bar click)
- here, n = pumpflag
- 0
- processes all files without checking for user input until processing is finished
- hidden
- (boolean) whether to include hidden files
- Optional, default is 0.
- Possible Values
- 1
- hidden files are included
- 0
- hidden files are not included
- Return Value
- Depending on the parameters, returns either:
- (string) command output
- (integer) count of all files processed
- Examples
- File.AllFiles("c:/windows","","1")
- counts all files under "c:/windows".
- File.AllFiles("c:/mypath/*.tmp", "file.delete('"|'")")
- deletes all .tmp files in c:/mypath but not its subfolders.
- File.AllFiles("c:/mypath", "debug |")
- lists all files in c:/mypath but not its subfolders.
- Notes
- Do not use this command to rename files as files may be reprocessed after renaming.
- Use File.IsFolder to identify folders when subfolders=2.
- Attrib
- Description
- Retrieves the attributes of a file or folder.
- Syntax
- Parameters
- path
- (string) path to the file or folder
- Return Value
- (string) the file or folder attributes
- Examples
- File.Attrib("C:/Program Files/PowerPro/pproconf.pcf")
- File.Attrib("C:/Program Files/PowerPro")
- Close
- Description
- Closes a file & frees the file handle.
- Syntax
- Parameters
- fh
- (integer) handle of the file to close
- Return Value
- Examples
- Global fh = File.Open(?"c:\myfile.txt", "r")
Win.Debug(fh)
fh = File.Close(fh)
Win.Debug(fh)
- Opens the file "myfile.txt" for reading, then closes it using the file handle, as stored in global variable fh.
The two Win.Debug() calls output:
101 (or whatever value is assigned for the file's handle)
1
- CloseAll
- Description
- Syntax
- Examples
- Notes
- This function only closes files that are open for reading or writing, not other documents..!
- Copy
- Description
- Copies a file to a destination file or folder.
- Syntax
- File.Copy(filepath1, filepath2, noerr)
- Parameters
- filepath1
- (string) path of the file to be copied
- filepath2
- (string) path to the target
- Possible Values
- folder path
- target file will keep original file name
- folder path + file name
- original file will be copied with new file name
- noerr
- (boolean) sets whether error messages will be shown
- Optional, default is 0.
- Possible Values
- 0
- error messages will be shown (default)
- 1
- Return Value
- (boolean) result will be either:
- Examples
- Local sFile = ?"c:\docs\names.txt"
if (File.Copy(sFile, ?"c:\archive\"), 1) do
Win.Debug("file copied successfully")
else
Win.Debug("copy of file", sFile, "failed")
endif
- CreateShortcut
- Description
- Creates a .lnk file shortcut to another file
- Syntax
- File.CreateShortcut(target, fpathlnk[, desc[, params[, iconpath[, iconindex]]]])
- Parameters
- target
- (string) Target of the shortcut file.
- fpathlnk
- (string) Location & name for the new shortcut file.
- PowerPro adds the .lnk extension if not supplied.
- desc
- (string) Description.
- Optional, defaults to target if omitted.
- params
- (string) Command line arguments.
- Optional.
- iconpath
- (string) Path to icon.
- Optional.
- iconindex
- (integer) Zero-based index to icon.
- Optional.
- Return Value
- (boolean) Returns either:
- 1
- shortcut created successfully
- 0
- Examples
- if (File.CreateShortcut(?"C:\Program Files\PowerPro\powerpro.exe", desktop, "this is a test", "", ?"C:\Program Files\PowerPro\powerpro.exe", 1)) do
Win.Debug("shortcut created")
else
Win.Debug("there was a problem & the shortcut was not created")
endif
- Notes
- Icon specified in parameter "iconpath" must be an icon.
- iconpath=*.exe with iconindex=1 does not work for me..?
- Delete
- Description
- Syntax
- Parameters
- filepath
- (string) path to the file or files to delete
- May contain wildcards.
- Examples
- File.Delete(?"c:\path\to\myfile.txt")
- The file "c:\path\to\myfile.txt" is deleted.
- File.Delete(?"c:\temp\*.log")
- Deletes all files with the extension ".log" in folder "c:\temp\".
- Notes
- Deleted items are sent to the Recycle Bin.
- DeleteNoRecycle
- Description
- Delete files or folders, bypassing the recycle bin.
- Syntax
- DeleteNoRecycle(filepath)
- Parameters
- filepath
- (string) path to the files or folder to delete
- Examples
- DeleteNoRecycle(?"c:\myfolder\myfile.txt")
- The file "c:\myfolder\myfile.txt" is deleted completely.
- DeleteNoRecycle(?"c:\temp\*.tmp")
- Completely deletes from the computer all files with extension ".tmp" in folder "c:\temp".
- EOF
- Description
- Syntax
- Parameters
- fh
- handle of the file to check
- Return Value
- non-zero
- 0
- previous File.ReadLine or File.ReadString call did not encounter EOF
- Examples
- local strPath, fh, str
strPath = "c:/mydocs/somefile.txt"
fh = File.Open(strPath, "r")
if (fh > 0) Do
for (lineNum=1;1;LineNum=LineNum+1)
str = File.ReadLine(fh)
if (File.EOF(fh))
break
; process the file line in variable str
endfor
else
MessageBox ("ok", "Error opening file: "++strPath)
endif
- The standard way to read a file line-by-line, using File.EOF to check when to stop reading.
- EndWatchFolder
- Description
- Ends a File.WatchFolder command.
- Syntax
- Parameters
- han
- (integer) handle of the watch to end
- Examples
- local wh = File.WatchFolder("path/to/folder", ?|win.debug("New file!")|, 0, "file")
File.EndWatchFolder(wh)
- Sets up a File.WatchFolder watch, assigning the handle to the variable wh, then ends the watch.
- Folder
- Description
- Returns the folder from specified file path.
- Syntax
- Parameters
- Return Value
- (string) folder portion of file path
- Examples
- Win.Debug( File.Folder("c:/path/to/file.txt") )
- This outputs:
c:\path\to.
- GetDate
- Description
- Retrieves the modified or created date & time of a file.
- Syntax
- Parameters
- path
- s
- (string) Sets which values to return.
- Possible Values
- "c" or "C"
- returns the created date and time
- "m" or "M"
- returns the modified date and time
- Return Value
- (string) Date string of 12 digits:
- Examples
- Win.Debug( File.GetDate(?"C:\Program Files\PowerPro\pproconf.pcf", "m") )
- Outputs the modified date & time of the file "C:\Program Files\PowerPro\pproconf.pcf".
- GetShortPath
- Description
- Retrieves the short (8.3) path to the specified file.
- Syntax
- Parameters
- fpath
- (string) path to the target file
- Return Value
- (string) the short, 8.3-style path to the file
- Examples
- File.GetShortPath("c:/documents and settings/administrator/desktop/test.txt")
- IsFolder
- Description
- Checks to see if a path is a valid path to a folder/directory.
- Syntax
- Parameters
- fpath
- (string) the path to check
- The path may _not_ contain wildcards.
- Return Value
- (boolean) whether path is valid:
- Examples
- File.IsFolder("c:/this/does/not/exist"))
- KSize
- Description
- Retrieves the file size of a file, in kilobytes (size/1024).
- Syntax
- Parameters
- Return Value
- (integer) file size in kilobytes
- (string) returns "" if file cannot be opened.
- Examples
- local s, fpath
fpath = ?"c:\mydocs\myfile.txt"
s = File.KSize(fpath)
Win.Debug(fpath, "is", s, "kb")
- LastModified
- Description
- Retrieves the last modified date and time of specified file.
- Syntax
- Parameters
- path
- (string) path to the file
- Return Value
- (string) date & time as 12 digits:
- Examples
- local s, fpath
fpath = ?"c:\stuff\myfile.txt"
s = File.LastModified(fpath)
Win.Debug(fpath, "was last modified on", formatdate("dd/M/yy", select(s,8)), ;;+
"at", formattime("hh:mm tt", remove(s,8)) )
- Retrieves Last Modified time of the file "c:\stuff\myfile.txt", then uses the string functions "select" and "remove" to format the datetime string for output.
- Notes
- File.LastModified does not work with folders.
- ListFiles
- Description
- Retrieves a list of files from a single folder in a multi-line string.
- Syntax
- File.ListFiles(path, subfoldersflag, pumpflag, hidden)
- Parameters
- path
- (string) path to the files
- Possible Formats
- path with filename & wildcards
- only files matching the path filter will be listed
- subfolders are not processed
- path without filename
- all files in the path's folder are listed.
- subfoldersflag
- (integer) specifies whether to include files in subfolders
- Optional, default is 0.
- Possible Values
- 2
- includes folder names in the list, but files in subfolders are not processed
- 1
- includes files in subfolders
- 0
- only files in the specified folder are listed
- pumpflag
- (integer) Keeps PowerPro responsive while files are being processed.
- Optional, default is 0.
- Possible Values
- n>0
- Every n files, PowerPro checks for user input to process, where n is the value of the pumpflag parameter.
- 0
- PowerPro finishes processing all files before checking again for user input
- hidden
- (boolean) Whether to include hidden files.
- Optional, default is 0.
- Possible Values
- 1
- hidden files are included
- 0
- hidden files are not included
- Return Value
- (multi-line string) the list of file paths
- Examples
- do(pickfile(File.ListFiles("c:/mp3",1),"Pick a song to play:"),"")
- Opens a PowerPro selection window enabling the user to pick a file from "c:\mp3", using File.ListFiles & the PowerPro function "pickfile" to generate the list of names of song files from the folder & its subfolders.
- File.ListFiles(?"c:\pics",0,30,1)
- Lists all files in "c:\pics", with PowerPro checking for other input every 30 files, & hidden files included.
- Notes
- Use File.IsFolder to identify folders when subfoldersflag is set to 2.
- The PowerPro function "line" can be used to cycle through each line of the list.
- The returned list can also be used as an argument to the "pickstring" or "pickfile" functions, to display a list of files for the user to select from.
- Move
- Description
- Moves a file to a destination file or folder.
- Syntax
- File.Move(filepath1, filepath2, noerr)
- Parameters
- filepath1
- (string) path to file to move
- filepath2
- (string) destination path
- Possible Values
- folder path
- moved file keeps original file name
- full file path
- moved file is given the file name specified by filepath2
- noerr
- (boolean) whether to show any errors
- Optional, default is 0.
- Possible Values
- 1
- 0
- any error messages will be shown
- Return Value
- (boolean) success indicator:
- 1
- file was moved successfully
- 0
- Examples
- if (not File.Move("c:/docs/file.txt", "c:/archive/text/", 1))
MessageBox("warning", "File could not be moved", "Error moving file")
- Notes
- File.Move has the same effect as renaming a file.
- Name
- Description
- Retrieves the file name from a file path, excluding the folder and type extension.
- Syntax
- Parameters
- path
- (string) target file path
- Return Value
- Examples
- local fn = File.Name("c:/path/to/myfile.doc")
MessageBox("ok", "filename is: "++fn, "Filename")
- Shows a message with "filename is: myfile".
- NameType
- Description
- Retrieves the file name and type extension from a full file path.
- Syntax
- Parameters
- path
- (string) target file path
- Return Value
- (string) file name & extension
- Examples
- Win.Debug(File.NameType("c:/music/mysong.mp3"))
- Open
- Description
- Opens a file and returns the file's handle for access to the file.
- Syntax
- fh = File.Open(path, howopen)
- Parameters
- path
- (string) path of the file to open
- howopen
- (string) single character indicating how file is to be opened
- Possible Values
- "r"
- opens the file to be read
- "w"
- opens the file to be written
- any & all previous content will be overwritten
- "a"
- opens the file to be appended to
- previous content will be kept, & new info added to end of file
- Return Value
- fh
- (integer) The file handle, or an error.
- Possible Values
- >0
- File was successfully opened, and the returned value, a positive integer, is the file handle.
- 0 or lower
- An error was encountered while opening the file.
- Examples
- Global fh = File.Open(?"c:\path\to\myfile.txt", "r")
if (fh>0) do
Win.Debug(File.ReadLine(fh))
else
Win.Debug("There was an error, possibly that the file was not found.")
endif
- Opens the file "c:\path\to\myfile.txt" for reading, & sets the global variable fh to the file handle.
- Notes
- Beware of backslashes in file paths -- they have special significance in normal strings, escaping the next character. Use the ?"" string delimiter:
fh = File.Open(?"c:\path\to\myfile.txt", "r")
- Long & 8.3 filepaths are accepted.
- R - Z
- ReadAll
- Description
- Reads an entire file into a single string variable.
- Syntax
- Parameters
- path
- (string) path to the file
- Return Value
- (string) the entire file contents as a single string
- Examples
- Local f = File.ReadAll(?"C:\Program Files\PowerPro\ErrorLog.txt")
Win.Debug("number of lines in error log:", line(f,0))
- ReadLine
- Description
- Reads and returns next line from file including any trailing \r or \n.
- Syntax
- Parameters
- fh
- (integer) handle of the file to read from
- Return Value
- (string) the line read from the file
- Examples
- Local fh = File.Open(?"c:\myfile.txt","r")
str = File.ReadLine(fh)
- Opens "c:\myfile.txt" for reading, and puts first line of file -- including any \n (newline) or \r (carriage return) characters -- into the variable str.
- Notes
- The maximum line length starts at 4K characters but can be set as large as 64K characters with File.SetMaxLine.
- ReadString
- Description
- Reads and returns next line from file, with any trailing \r and \n removed.
- Syntax
- Parameters
- fh
- (integer) handle of the file to read from
- Return Value
- (string) contains the line read from the file
- Examples
- Local fh = File.Open(?"c:\myfile.txt","r")
str = File.ReadString(fh)
- Opens "c:\myfile.txt" for reading, and puts first line of file into the variable str.
- Notes
- The maximum line length starts at 4K characters but can be set as large as 64K characters with File.SetMaxLine.
- See Also
- Restart
- Description
- Restarts reading or writing of a file from the beginning, so that the next operation on this file will occur at the start of the file.
- Syntax
- Parameters
- fh
- (integer) handle of the file to restart
- Examples
- Local fHan = File.Open("myfile.txt", "r")
File.ReadLine(fHan)
File.Restart(fHan)
File.ReadLine(fHan)
- Opens "myfile.txt" for reading, reads the first line, restarts the file & reads first line again.
- Resolve
- Description
- Resolves a shortcut or retrieves specified information about a shortcut.
- Syntax
- File.Resolve(fpath, info)
- Parameters
- fpath
- (string) path to the shortcut file
- info
- (string) determines which result the File.Resolve call returns
- Optional, if omitted, the File.Resolve call will return the path to the shortcut's target file.
- Possible Values
- "par" or "parameters"
- returns the parameters set for the shortcut
- "des" or "description"
- returns the shortcut's description or comment
- "wor" or "work"
- returns the work folder specified for the shortcut
- "ico" or "icon"
- returns the path to the icon used for the shortcut
- Return Value
- (string) Information about the shortcut file
- Possible Values
- shortcut's target file path
- shortcut's parameters
- info is set to "par" or "parameters"
- shortcut's description/comment
- info is set to "des" or "description"
- shortcut's work folder
- info is set to "wor" or "work"
- shortcut's icon path
- info is set to "ico" or "icon"
- Examples
- Local p = ?"C:\Documents and Settings\Administrator\Start Menu\Command Prompt.lnk"
Win.Debug(File.Resolve(p,"des"))
Win.Debug(File.Resolve(p,"par"))
Win.Debug(File.Resolve(p,"wor"))
Win.Debug(File.Resolve(p,"ico"))
Win.Debug(File.Resolve(p))
- Would output to a PowerPro Debug window the following [in the reverse order in the PowerPro Debug window]:
"Performs text-based (command-line) functions."
""
"%HOMEDRIVE%%HOMEPATH%"
"%SystemRoot%\system32\cmd.exe"
"C:\WINNT\system32\CMD.EXE"
Note the empty string returned for the parameters query as that shortcut has none.
- RunAs
- Description
- Runs a program under another userid & password.
- Only for Windows 2000 and later.
- Syntax
- File.RunAs(uid, pw, exepath, cmdline, workdir)
- Parameters
- uid
- (string) user id
- The user id string may also include a domain:
- File.RunAs("uid@domain", "upw", "c:/path/pgm.exe")
- pw
- exepath
- (string) full path to the program file to be run, including file name & extension
- cmdline
- (string) command arguments
- Optional
- workdir
- (string) working directory for program
- Optional
- Return Value
- 1
- program was run successfully
- 0
- Examples
- File.RunAs("admin", "adminpw", "n:/path/to/admin/pgm.exe", "%1", "s:/network")
- Opens "pgm.exe" as "admin" (with password "adminpw"), with parameter "%1" & work directory "s:/network".
- File.RunAs("joe", "abc123", ?"c:\path\to\pgm.exe", ;;+
"myfile.doc", ?"d:\users\joe\docs")
- Runs "pgm.exe" as user "joe" with password "abc123", opening it with parameter "myfile.doc" & current work directory "d:\users\joe\docs".
- File.RunAs("joe", "abc123", ?"c:\programs\mozilla\thunderbird.exe", "-addressbook")
- Opens Thunderbird's Address Book as user "joe" with password "abc123".
- File.RunAs( "username@domain", "password", _file_ )
- This could be added to the Context command list for file context menus, to automatically run the highlighted file with predefined credentials of "username@domain" & "password".
- Suggested by David Troesch on the PowerPro list, 12/11/2005
- RunAsWait
- Description
- Runs a program under another userid and password, & waits for it to finish.
- Only for Windows 2000 and later.
- Syntax
- File.RunAsWait(uid, pw, pgmpath, cmdline, workdir, maxwait)
- Parameters
- uid
- pw
- exepath
- cmdline
- (string) command arguments
- Optional.
- Depending on the program run, cmdline may have to start with the path to the program (in double quotes if blanks included).
- workdir
- (string) work directory for program
- Optional.
- maxwait
- (integer) sets maximum wait time in milliseconds
- Optional, default is 0.
- Possible Values
- maxwait > 0
- waits at most maxwait milliseconds for program to finish
- 0
- waits until program finishes
- Return Value
- (string) the result of the command
- Examples
- File.RunAsWait("admin", "adminpw", "c:/path/to/pgm.exe", "", "n:/files", 10000)
- Runs program "pgm.exe" under user id "admin", setting current work directory to "n:/files", & waits up to a maximum of 10 seconds for the program to complete.
- RunCallback
- Description
- Runs a program & executes a PowerPro command when it terminates, or when specified wait period ends.
- Syntax
- File.RunCallback(maxwait, PProCmd, pgmpath, params, work, howstart)
- Parameters
- maxwait
- (integer) Maximum number of milliseconds to wait for program to finish
- Possible Values
- 0
- no maximum wait
- I assume this means wait forever..?
- maxwait>0
- waits up to maxwait milliseconds
- PProCmd
- (string) PowerPro command, executed when the the program in parameter "pgmpath" ends or maxwait milliseconds elapse.
- PProCmd can be any valid PowerPro command, including script calls.
- pgmpath
- (string) Full path to the program to run.
- Program can be an .exe, .bat, or .cmd application.
- params
- (string) Program command parameters.
- Optional.
- work
- (string) Program work directory.
- Optional.
- howstart
- (string) How to start the program.
- Optional.
- Possible Values
- Global Variables
- _exit_
- Set to either:
- the program's exit code
- 9999999
- Examples
- File.RunCallback(60000, ".checkIt", "c:/pgms/printreport.exe", "-all -pdf", ;;+
"d:/data/reports/"++formatdate("MM",date), "min")
- Runs the program "printreport.exe" minimized, with parameters "-all -pdf" & in folder "d:/data/reports/MM", where MM is the month with leading zero.
- File.RunCallback(10000, ;;+
"messagebox(\"ok\", \"Program completed or timer expired\", \"Done!\")", ;;+
"cmd.exe", "-dir", ?"c:\temp")
- Notes
- Each File.RunCallback command activates a new thread, so you can use as many as you want.
- A File.RunCallback command returns immediately & the next PowerPro command is run, but the wait created by the call continues until maxwait is reached or the program ends.
- RunWait
- Description
- Runs a program, & waits until it terminates.
- Syntax
- File.RunWait(maxwait, pgmpath, params, workdir, howstart)
- Parameters
- maxwait
- (integer) maximum time to wait in milliseconds
- Possible Values
- maxwait>0
- waits up to maxwait milliseconds
- 0
- no maximum wait
- I assume this means it waits forever..?
- pgmpath
- (string) path to the program to run
- Program can be an .exe, .bat, or .cmd file.
- params
- (string) command line parameters
- Optional.
- workdir
- (string) work directory for program
- Optional.
- howstart
- (string) how to start the program
- Optional.
- Possible Values
- "max"
- "min"
- "hide"
- "normal"
- runs program at normal size
- Return Value
- (integer) Either:
- exitcode
- the exit code of the program
- 9999999
- Examples
- Local succ = File.RunWait(10000, "deveject", "-EjectName:\"WLAN*\"")
Win.Debug(succ)
- Waits up to 10 seconds for the program "deveject" to eject an external device, and outputs the result, or 9999999 if the program hasn't completed yet.
- Notes
- Note that the specified program continues running after maxwait is reached -- it's only the File.RunWait call that has finished & returned its result.
- SetDate
- Description
- Sets the modified or created date of a file.
- Syntax
- File.SetDate(path, s, date, time)
- Parameters
- path
- (string) Path to the file.
- s
- (string) Determines whether to change the Created or Modified value.
- Optional, default is "m".
- Possible Values
- "c" or "C"
- changes the created date and time
- "m" or "M"
- changes the modified date and time
- date
- (integer) The date as eight digits yyyymmdd.
- Optional, default is today.
- time
- (integer) The time as six digits hhmmss.
- Optional, default is now.
- Examples
- File.SetDate("c:/docs/map.mm", "c", 20051101, 022319)
- Sets the created date of the file "map.mm" to 1-nov-05 2:23am.
- SetMaxLine
- Description
- Sets maximum line length for subsequent File.ReadLine or File.ReadString calls.
- Syntax
- Parameters
- n
- (integer) maximum line length value
- Possible Values
- Examples
- Size
- Description
- Retrieves the size of a file in bytes.
- Syntax
- Parameters
- Return Value
- Returns either:
- (integer) file size in bytes
- "" (empty string) indicating the file cannot be opened
- Examples
- Win.Debug(File.Size(?"C:\program files\powerpro\powerpro.exe"),"bytes")
- Size64
- Description
- Returns the size of a file as a 64-bit integer.
- Syntax
- Parameters
- path
- (string) path to the file
- Return Value
- (integer) 64-bit integer value
- Examples
- Win.Debug(File.Size64("c:/path/to/some.doc"))
- Notes
- Use the int64 plugin to work with 64-bit integers.
- Type
- Description
- Retrieves the extension of a file excluding the leading period.
- Syntax
- Parameters
- path
- (string) path to the file
- Return Value
- (string) file type (extension) without leading period
- Examples
- Win.Debug( File.Type("c:/path/to/file.doc") )
- ValidPath
- Description
- Checks if supplied argument string is a valid file or folder path.
- Syntax
- Parameters
- fpath
- (string) the string to check
- May contain wildcards.
- Return Value
- (boolean)
- 1
- fpath is a valid path to a file or folder
- 0
- fpath is not a valid path
- Examples
- sFile = sUserPath ++ "docs/times.txt"
if (not File.ValidPath(sFile))
messagebox("error ok", "File not found", "File Error")
- Checks if the string in variable sFile, made up of a base path previously defined & assigned to sUserPath and "docs/times.txt", is a valid file, & shows an error message if not.
- Version
- Description
- Retrieves the version information of a file.
- Syntax
- Parameters
- path
- (string) path to the file
- Return Value
- (string) either:
- "n1 n2 n3 n4"
- file version info as four blank separated numbers
- "" (empty string)
- file has no version information
- Examples
- Win.Debug( File.Version("c:/program files/powerpro/powerpro.exe") )
- Outputs: "4 3 0 8" (or the current version of PowerPro installed).
- Volume
- Description
- Retrieves the volume name for the specified file path.
- Syntax
- Parameters
- path
- (string) path to the file
- Return Value
- (string) the file path's volume name
- Examples
- Win.Debug( File.Volume("c:/path/to/file.ext") )
- Notes
- I can't get this to return anything..?
- WatchFolder
- Description
- Runs a command when a folder's contents change.
- Syntax
- File.WatchFolder(path, cmd, maxwait, keywords)
- Parameters
- path
- (string) path to the folder to watch
- cmd
- (string) PowerPro command to execute when folder changes
- For W2K and later, if the cmd ends in a comma then a parenthesis, for example, "myscript(,)", then the folder name and the file name are inserted as the last two arguments.
It is recommended that this approach be used if you have multiple outstanding watches, as if more than one watch ends at the same time, it is possible that the global variables will be overwritten.
- maxwait
- (integer) maximum wait time in milliseconds
- Optional, if omitted (or set to 0) there is no maximum wait.
- keywords
- (string) string of blank-separated keywords that configure the watch
- Optional, default is "file".
- Possible Values
- file
- monitor for new, deleted or renamed files
- folder
- monitor for new, deleted or renamed folders
- lastwrite
- monitor for changes in last write date (last modified date) of files or folders
- size
- monitor for changes in file sizes
- security
- monitor for changes in security settings of file
- subtree
- monitor subfolders of path as well
- Return Value
- (integer) watch handle
- The returned handle can be used to end the watch with the command:
File.EndWatchFolder(han)
- Global Variables
- _folder_
- Set to the folder being watched.
- _exit_
- Set to a value between 0 & 5 that indicates how the folder changed.
- Possible Values
- 0
- 1
- 2
- 3
- 4
- file or folder attributes changed
- 5
- For Win 95/98/Me, _exit_ is only ever set to 1 or 0.
- _file_
- Set to the name of the changed file (omitting the path to the watched folder).
- For Win 95/98/Me, _file_ is set to "".
- Examples
- local fh = File.WatchFolder("c:/docs/myfolder", ?#win.debug("New file!")#, 0, "file folder subtree")
- Sets up a watch on the folder "c:\docs\myfolder" and its subfolders, for files or folders to be added, deleted, or renamed.
- Notes
- Each File.WatchFolder call activates a new thread, so you can use as many as you want.
- A File.WatchFolder call only watches for one change. Once the change event occurs, the watch ends.
- WriteAll
- Description
- Writes or appends specified string to file.
- Syntax
- File.WriteAll(fpath, str, append)
- Parameters
- fpath
- (string) path to the file
- If the file does not exist, it is created.
- str
- (string) text to put in file at fpath
- append
- (boolean)
- 1, or any char
- string is appended to file contents
- 0, "" (empty string), or omitted
- file contents are overwritten
- Optional, default is 0.
- Examples
- File.WriteAll(?"c:\docs\zz.txt", "something to add\n", 1)
- Appends the text "something to add" plus a line return to the file "c:\docs\zz.txt".
- File.WriteAll(?"C:\Web\cliptest\mostrecent.txt", clip++"\n")
- Overwrites the file mostrecent
- WriteLine
- Description
- Writes a string to a file, including the closing \r\n to make a complete line.
- Syntax
- Parameters
- fh
- handle of file to write to
- str
- (string) the string to write to the file
- Examples
- File.WriteLine(fHan, "Quick brown fox")
- Writes the line "Quick brown fox\r\n" to the file represented by fHan.
- File.WriteLine(fHan, "")
- Writes just a "\r\n" to the file given by fHan.
- Terminates any lines partially written with File.WriteString.
- Notes
- If the str already ends in a CR (\r) or NL (\r), none is added.
- WriteString
- Description
- Writes a string to a file, without adding "\r\n" at the end.
- Subsequent File.WriteLine or File.WriteString calls will add text to same line.
- Syntax
- File.WriteString(fh, str)
- Parameters
- fh
- handle of file to write to
- str
- (string) the string to write to the file
- Examples
- File.WriteString(fh, "The")
File.WriteString(fh, "quick brown")
File.WriteString(fh, "fox")
- Each string is written to the file given by fh, & all will be on the same line.
- By Category QuickRef
- Check Information
- Delete a File
- Execute a File
- RunAs
- RunAsWait
- RunWait
- RunCallback
- Execute a Command
- Get File Information
- AllFiles
- Attrib
- Folder
- GetDate
- GetShortPath
- KSize
- LastModified
- Name
- NameType
- Size
- Size64
- Type
- Version
- Get File System Information
- Open/Close a File
- Read/Write Operations
- Copy
- Move
- ReadAll
- ReadLine
- ReadString
- Restart
- SetMaxLine
- WriteAll
- WriteLine
- WriteString
- Set Information
- Shortcuts
- Notes
- The File plugin allows a maximum of 15 files to be open simultaneously.
- See "file.txt" in the PP\plugins folder for more information & examples.
- Make sure to use the ?"" delimiter for filepaths with backslashes.
- Float
- Author
- Overview
- The float plugin lets you do arithmetic with floating point numbers.
- Commands
- Add
- Description
- Adds up to nine numbers and returns the result.
- Syntax
- Float.Add(r1, r2, ..., r9)
- Parameters
- r1, r2, ..., r9
- (string) up to 9 comma-separated numbers, as strings
- Return Value
- (integer) sum of the parameters
- Examples
- Win.Debug( Float.Add("1.1", "2.2", "3.3") )
- Outputs 6.6 to a debug window.
- local r2 = Float.Add(8, "6.6")
- Sets local variable r2 to 14.6.
- Compare
- Description
- Compares two numbers & returns the result.
- Syntax
- Parameters
- r1, r2
- (number) the two numbers to compare
- Return Value
- Examples
- Win.Debug( Float.Compare("0.00021", "2.1e-4") )
- Outputs "0" to a debug window, because the two numbers are equal.
- Win.Debug( Float.Compare(4, 30) )
- Outputs "-1" to a debug window, because the first number is less than the second.
- Ceiling
- Description
- Rounds a value up to the next whole number.
- Syntax
- Parameters
- r1
- (number) the value to round up
- Return Value
- (number) a whole number value > r1
- Examples
- Win.Debug( Float.Ceiling("2.833") )
- Outputs "3" to a debug window, which is the next whole number after 2.833.
- Win.Debug( Float.Ceiling("-2.3") )
- Outputs "-2" to a debug window, which is the next whole number after -2.3.
- See Also
- Divide
- Description
- Divides one number by another.
- Syntax
- Parameters
- r1
- (number) first value (dividend)
- r2
- (number) value to divide by (divisor)
- Return Value
- (number) resultant value (quotient)
- Examples
- Win.Debug( Float.Divide(8, "3.3") )
- Outputs "2.42424" to a debug window.
- ForcePeriod
- Description
- Specifies whether to force use of period for floating point values, or to use the system's regional settings.
- Syntax
- Parameters
- n
- (boolean) whether or not to force the period
- Possible Values
- 1
- the period is used as the decimal point
- 0
- the regional settings active when PowerPro started are used
- Examples
- Float.ForcePeriod(1)
- Tells PowerPro to use a period as the decimal point.
- Notes
- The Float plugin starts with ForcePeriod set to 1; the Float2 plugin starts with it set to 0.
- Format
- Description
- Formats a floating point value as specified.
- Syntax
- Float.Format(r1, notation, num_chars, num_dec, regional)
- Parameters
- r1
- (number) floating point value
- notation
- (string) single character indicating which floating value notation to use
- Possible Values
- e
- f
- g
- use f if possible, e otherwise.
- num_chars
- (number) number of characters wide
- num_dec
- (number) number of decimal places
- regional
- (string) single character indicating whether to use regional settings to determine the decimal point character, or whether to use a period.
- Optional, default is to fall back on Float.ForcePeriod() setting.
- Possible Values
- r
- regional settings are used
- .
- Return Value
- (number) the formatted value
- Examples
- Win.Debug( Float.Format("2.3678", "e", 3, 1, ".") )
- Outputs "2.4e+000" to a debug window.
- Win.Debug( Float.Format("26.8235", "f", 4, 2) )
- Outputs "26.82" to a debug window.
- Win.Debug( Float.Format("2.2e-4", "g", 6, 1) )
Win.Debug( Float.Format("2.2e-4", "g", 7, 1) )
Win.Debug( Float.Format("2.2e-4", "f", 6, 1) )
- Outputs "0.0002", then " 0.0002", then " 0.0" to a debug window.
- why the spaces?
- See Also
- Mul
- Description
- Multiplies up to nine numbers together.
- Syntax
- Float.Mul(r1, r2[, ..., r9])
- Parameters
- r1,r2,...,r9
- (number) 2 to 9 numbers to be multiplied together
- Return Value
- Examples
- Win.Debug( Float.Mul("0.5", "0.25") )
- Outputs "0.125" to a debug window.
- Sub
- Description
- Subtracts one number from another.
- Syntax
- Parameters
- r1
- r2
- (number) value to subtract from r1
- Return Value
- Examples
- Win.Debug( Float.Sub("3.95", "1.1") )
- Outputs "2.85" to a debug window.
- Win.Debug( Float.Sub("1.1", "3.95") )
- Outputs "-2.85" to a debug window.
- Truncate
- Description
- Rounds a number down to the previous whole number.
- Syntax
- n1 = Float.Truncate(r1)
- Sets n1 to next whole number smaller than r1.
- To round a number, you can use Float.Truncate(Float.Add(r1,"0.5"))
- Parameters
- r1
- (number) the initial value to be truncated
- Return Value
- (number) the resultant whole number value
- Examples
- Win.Debug( Float.Truncate("-2.3") )
- Outputs "-3" to a debug window, which is the previous whole number.
- Win.Debug( Float.Truncate("3.1e5") )
- Outputs "310000" to a debug window, which is the previous whole number.
- See Also
- Notes
- Any numbers with a decimal point *must be in quotes*.
- Both decimal points & exponent notation are accepted for float values.
- See Also
- See the file Float.txt in PowerPro's Plugins directory for more information on using this plugin.
- GetSystemPerformanceData
- Authors
- Juan Lupion & Bruce Switzer
- Portions by Jeff Lundgren
- Ini
- Author
- Alan Campbell aka entropyreduction
- Int64
- KeyTrap
- Author
- Overview
- Services
- AddEntry
- Description
- Add a new entry temporarily & dynamically.
- Syntax
- KeyTrap.AddEntry(sName, sEntry)
- Parameters
- sName
- (string) a name for this entry
- Maximum length of sName = 8 characters.
- If this name is already existing (either in INI file, or by a previous call to AddEntry), the old value will be overwritten.
- This name will also be used to remove this entry.
- sEntry
- (string) a valid INI file entry
- Return value
- (boolean)
- 1
- The entry was added successfully.
- 0
- The entry was not added due to some errors.
- Examples
- local sTemp= "0,0,0,106,166,1,,,win.debug("add"),1,1"
KeyTrap.AddEntry("jump", sTemp)
- Notes
- The entry added via this service...
- will not be stored in the INI file
- is active only while:
- KeyTrap.ReloadIni() is not executed.
- Keytrap is not unloaded.
- PP is not restarted.
- Useful when you want to disable some keys (or the whole keyboard) temporarily.
- After running this service, the new entry is active immediately.
- Enable
- Description
- Enable/Disable KeyTrap plugin service.
- Syntax
- KeyTrap.Enable(param1, param2)
- Parameters
- param1
- (boolean) Determines whether KeyTrap is being enabled or disabled.
- Possible Values
- param2
- (boolean) Tell KeyTrap whether to auto-load the default ini file.
- Optional.
- Possible Values
- Result
- Examples
- if (KeyTrap.Enable(1,1))
Win.Debug("KeyTrap default ini file loaded")
- KeyTrap.Enable(0)
KeyTrap.Unload()
- Notes
- If this service is not called, KeyTrap is disabled by default.
- GetEntry
- Description
- Returns the value of an entry.
- Return values
- Examples
- Notes
- GetKeyName
- Description
- Returns the name of a key
- Return values
- Examples
- Notes
- GetKeyState
- Description
- Returns the toggled or pressed state of the specified key.
- Syntax
- Parameters
- x
- (boolean) Whether to check for toggle state or pressed state.
- Possible Values
- 1
- Returns the toggle state of a key.
- Used for checking the toggle state of CAPS, NUM, and SCROLL Lock.
- 0
- Returns the pressed state of a key.
- Use for all other non-toggle keys.
- y
- (integer) The virtual key code of the key to check.
- Return values
- (boolean) Either:
- 1
- key is pressed or is in ON state.
- 0
- key is not pressed or is in OFF state.
- Examples
- Win.Debug( KeyTrap.GetKeyState(1,20) )
- Checks for the toggle state of the caps lock.
- Notes
- This function does not require Enable() to be executed first.
- Execute Keytrap.ScanMode(1) to check the vkcode of the keys, or refer to the file vkcodes.htm.
- GetPressedKeys
- Description
- Identifies the keys that are depressed
- Return values
- Examples
- Notes
- GetScanCode
- Description
- Waits for the next single keystroke & returns its scan code.
- Syntax
- Parameters
- n
- (integer) Maximum wait time in seconds.
- Optional, default value is infinite.
- Return value
- Examples
- ScanCode = KeyTrap.GetScanCode()
- Waits for an infinite amount of time for the next single keystroke, then returns its scan code.
- ScanCode = KeyTrap.GetScanCode(120)
- Waits up to 120 seconds for the next single keystroke, then returns its scan code, unless no keystroke occurs in that time, in which case the call returns -1.
- GetVkCode
- Description
- Waits for a single keystroke and returns its virtual-key code.
- Syntax
- Parameters
- n
- (integer) Timeout value in seconds.
- Optional, default value is infinite.
- Return value
- (integer) Either:
- Virtual-key code (vkcode) of the key
- -1
- Examples
- VkCode = KeyTrap.GetVkCode(100)
- Waits up to 100 seconds for the next keystroke & returns it vkcode, unless no keystroke occurs, in which case the call returns -1.
- IsEnable
- Description
- returns 1 is keytrap is enabled
- Syntax
- Parameters
- Return values
- Examples
- Notes
- ListEntry
- Description
- List all the entries loaded in memory
- Syntax
- Parameters
- Return values
- Examples
- Notes
- ReloadIni
- Description
- Reloads the file "keytrap.ini".
- Syntax
- KeyTrap.ReloadIni(param1, param2, param3)
- Parameters
- param1
- (boolean) Suppress error message if loading of ini file has failed.
- Optional
- if omitted, the default behaviour is to display the message box.
- Values
- 1
- Suppress the error message box.
- 0
- Display error message box if error occurs.
- param2
- (string) section name to load from the ini file
- Optional, default is "Active".
- param3
- (string) ini file to load
- Optional, if not provided, keytrap will search for the default ini file in the order:
1. pprofolder\keytrap.ini
2. pprofolder\plugins.ini (common ini file for plugins)
- Return Value
- 1
- Operation was successful.
- 0
- Operation failed, for whatever reason.
- Examples
- KeyTrap.ReloadIni(0)
- KeyTrap.ReloadIni(0, "WarCraft")
- KeyTrap.ReloadIni(0, "WarCraft", "MyIniFile.ini")
- Notes
- See "KeyTrap.txt" in PowerPro plugins directory for more information.
- RemEntry
- Description
- Temporarily remove an entry
- Syntax
- Parameters
- Return values
- Examples
- Notes
- ResetKeys
- Description
- Syntax
- Parameters
- Return values
- Examples
- Notes
- ScanMode
- Description
- Turns "scan mode" (keyboard detection mode) on or off.
- In "scan mode", PowerPro traps all keys typed, & outputs their Scan & VK codes to a PowerPro debug window.
- Syntax
- Parameters
- tog
- 1
- 0
- Disable Scan mode
- see ScanMode Notes for alternative disable method
- Examples
- Notes
- To exit from scan mode: <ESC><ESC>
i.e. press Esc twice, & ScanMode will automatically be set to disabled.
- SendKeys
- Description
- An alternative method of sending keys to Win.Keys.
- Simulate key press in one of 2 ways
- 1. Using PP's *Keys command.
- equivalent to:
keytrap.enable(0)
*keys parameter
keytrap.enable(1)
- 2. Using the SendInput API.
- Precise control over keypress simulation.
- Don't forget to send a keyup event after a keydown event.
- Syntax
- KeyTrap.SendKeys(x)
- uses PP's *Keys command
- Parameters
- x
- (string) any value that is valid for Win.Keys
- KeyTrap.SendKeys(a,b,c,d)
- uses SendInput API
- Parameters
- a
- b
- (integer) virtual key code
- c
- (boolean) key up/down state
- Possible Values
- d
- (boolean) Sets whether to generate the vkcode by using the scancode in parameter a. If so, ignores supplied vkcode in parameter b.
- Optional; default is 0.
- Possible Values
- 1
- 0
- use vkcode in parameter b
- Examples
- KeyTrap.SendKeys(15,9,0) ;; keydown
KeyTrap.SendKeys(15,9,1) ;; keyup
- press and release Tab key
- KeyTrap.SendKeys("test{en}")
- sends "test" then <Enter>
- SetCtrlAltDel
- Description
- Enable/Disable <CTRL>+<ALT>+<DEL> keyboard combination.
- Syntax
- KeyTrap.SetCtrlAltDel(tog)
- Parameters
- tog
- 1
- enable <ctrl>+<alt>+<del>
- 0
- disable <ctrl>+<alt>+<del>
- Examples
- Notes
- On NT-based OS's, calling KeyTrap.SetCtrlAltDel(0) will prevent Task Manager from displaying.
- The Enable() service need not be called when using this service.
- Trap
- Description
- Enable/Disable the filtering of keys.
- Similar to the "Enable" service, but this service does not hook or unhook the DLL from the keyboard hook.
- Syntax
- Parameters
- Examples
- Notes
- Useful if you want to trap keys then send them with PP's *Keys command.
Ensure you disable the filtering of keys prior to sending the *Keys command, otherwise KeyTrap will re-trap that key sent by PP. - See KeyTrap.txt for more info.
- WaitKey
- Description
- Waits for the specified key to be pressed before returning.
- Can be used to pause a running script & continue only until a specific key has been pressed.
- Syntax
- Parameters
- x
- (integer or string) The virtual key code of the key to wait for.
- Optional, if omitted, the KeyTrap.WaitKey service is cancelled by the empty KeyTrap.WaitKey() call.
- Possible Values
- 0
- (integer) waits for any key
- vk
- (integer) wait for key specified by vkcode vk
- "vk1,vk2,...,vkn"
- (string) sends multiple vkcodes as a single comma-separated string of vkcodes
- WaitKey will return if any one of the specified keys was pressed.
- x = "c1,c2,...,cn"
- where each cn is a valid vkcode
- omitted
- Cancelling the WaitKey service
- Call WaitKey() without any parameters
- y
- (boolean) Determines whether KeyTrap should eat this key or pass it to the system.
- Optional; default is 1.
- Possible Values
- 1
- 0
- pass the key to the system
- n
- (integer) Timeout value in seconds.
- Optional, default value is infinity.
- Return values
- (integer) one of:
- vk
- where vk is the vkcode of the key pressed
- -1
- 0
- service ended for other reasons
- Examples
- KeyTrap.WaitKey("9,8,32")
- Waits for one of the 3 keys specified, then returns to the calling script.
- KeyTrap.WaitKey("9,8,32", 0, 60)
- Waits up to 60 seconds for one of the 3 keys specified, then passes the key on to the system & returns to the calling script.
- Local next = KeyTrap.WaitKey(0)
- Waits for any key to be pressed, & sets the local variable "next" to value of the pressed key's vkcode.
- KeyTrap.WaitKey(9)
Win.Debug("Returned")
- Waits for <tab> to be pressed, then returns & shows a debug message.
- Keytrap.WaitKey()
- Cancels the KeyTrap.WaitKey service.
- Notes
- You must call KeyTrap.Enable(1) before using this service.
- Do not call KeyTrap.Unload() if this service has not returned yet.
To unload when this service has not returned, cancel the WaitKey service first.
- Virtual key codes for mouse actions are not supported.
- Unload
- Description
- Usage
- Examples
- KeyTrap.Enable(1)
KeyTrap.WaitKey(13)
KeyTrap.Enable(0)
KeyTrap.Unload()
- Enables the KeyTrap service, waits for <Enter> to be pressed, then disables the service & unloads it.
- Notes
- KeyTrap.Enable(0), which disables the KeyTrap service, must be called before using KeyTrap.Unload().
- Mail
- Author
- Alan Campbell aka entropyreduction
- Map
- Author
- Overview
- The map plugin lets you work with lookup tables.
- A map is like a list of key-value pairs , where both key and value are any text. So:
map(key) = value
- The map plugin can support at most 50 simultaneously active maps.
- Maps store & retrieve keys in an unspecified order; see the Vec plugin for ordered numerical arrays.
- See map.txt in the PowerPro\plugins folder for more information & examples.
- Commands
- Capacity
- Description
- Returns total number of slots in lookup table.
- Syntax
- Parameters
- Return Value
- Examples
- Local mapCap = Map.Capacity(myMap)
- Sets local variable mapCap to the capacity of map myMap.
- Notes
- The actual value of Map.Capacity is a power of 2 greater than the size specified by Map.Create, calculated automatically by PowerPro. It is calculated as follows:
If:
m = Map.Create(n),
c = Map.Capacity(m), and
c = 2^i
then:
---n----- ---c----- ---i-----
0-256 256 8
257-512 512 9
513-1024 1024 10
... ... ...
etc.
- Create
- Description
- Creates a new map and returns its handle.
- Syntax
- m = Map.Create(size, useCase)
- Parameters
- size
- Expected number of elements in the map, if possible to predict.
- Allows for very fast access to each key and value.
- useCase
- Determines whether case of map keys is used.
- Optional; default value is 0
- Values
- 1
- case of letters in keys will be used.
- 0
- case of letters in keys is ignored
- Return Value
- Examples
- m = Map.Create(20)
- Creates a map with twenty elements.
- m = Map.Create(2, 1)
m["fruit"] = "peach"
m["Fruit"] = "pear"
- Creates a map with two elements:
- the 1st with key "fruit" & value "peach"
- the 2nd with key "Fruit" and value "pear".
- Delete
- Description
- Removes key and corresponding value from map, & decreases Map.Length by 1.
- Syntax
- Parameters
- Examples
- Local myMap = Map.Create(2)
myMap["hair"] = "brown"
myMap["age"] = "33"
Map.Delete(myMap, "hair")
- Creates a map with 2 elements, "hair" & "age", then deletes element "hair".
myMap then contains just one element, "age".
- DeleteAll
- Description
- Removes all key-value pairs from a map.
- Syntax
- Parameters
- Examples
- Local myMap = Map.Create(1)
myMap["product"] = "ice cream"
myMap["flavour"] = "chocolate"
Map.DeleteAll(myMap)
- Creates a map, myMap, and adds 2 elements to it, "product" & "flavour", then deletes all key/value pairs from myMap to leave an empty map (still named myMap) with Map.Length = 0.
- Notes
- Destroy
- Description
- Destroys a map, de-allocates all of its memory, frees its handle, & returns 0.
- Syntax
- Parameters
- Return Value
- Examples
- myMap = Map.Destroy(myMap)
- EOF
- Description
- Checks if Map.GetNext is at the last key of a map.
- Syntax
- Parameters
- Return Value
- bVal
- 1
- map.length is 0, or
- preceding Map.GetNext call failed because there were no more keys to retrieve.
- 0
- there is at least one key in map m, and
- previous Map.GetNext call returned a key.
- Examples
- key = Map.GetNext(m)
if (Map.EOF(m)) do
Win.Debug("No more keys left")
else
Win.Debug(key, m[key])
endif
- Gets the value of the next key in map m, and outputs a debug message that depends on whether or not Map.GetNext was at the last key.
- Notes
- "EOF" is common shorthand for the last item in a file, or in an object, etc. Short for "end of file".
- Exists
- Description
- Returns 1 if m is a valid map; 0 otherwise.
- Syntax
- Parameters
- Return Value
- Examples
- if (Map.Exists(m))
Win.Debug("lookup table exists")
- Get
- Description
- Retrieves string at specified key.
- Syntax
- Parameters
- Return Value
- val
- ""
- Returns an empty string if key k in map m does not exist.
- Examples
- Local dayCount = Map.Get(mapScores, "totalDays")
- Sets a local variable, dayCount, to the value of mapScores["totalDays"]
- Notes
- Alternative to:
val = m[k]
- GetNext
- Description
- Allows maps keys to be retrieved in a variable order.
- Syntax
- Parameters
- Return Value
- Examples
- map.restart(m)
for (1)
key = map.getnext(m)
if (map.eof(m))
break
win.debug(key, m[key])
endfor
- Loops through all the key-value pairs in a map m, and outputs their values to a debug window, breaking out of the loop when there are no more keys left. Uses Map.Restart to initialise Map.GetNext to the first key.
- Notes
- The order of key retrieval is arbitrary and may change if you add or remove elements.
- Use Map.GetNext with Map.Restart to initialize and Map.EOF to check for no more keys.
- Length
- Description
- Returns the number of key-value pairs in map.
- Syntax
- Parameters
- Return Value
- Examples
- map_len = Map.Length(myMap)
- sets variable "map_len" to the length of map "myMap"
- LocalCopy
- Description
- Creates a reference to a map which has been passed as an argument.
- Syntax
- Local m = Map.LocalCopy(arg(n))
- Parameters
- n
- index of function argument that contains the map to copy
- Return Value
- m
- a copy of the map in arg(n)
- Examples
- Local m = Map.LocalCopy(arg(1))
- Notes
- Must be used to create local variables when using a map passed as an argument.
If you simply say:
; WRONG
local m
m=arg(1)
then the local map m is destroyed when your routine exits, which will also destroy whatever map was passed as arg(1).
- Restart
- Description
- Resets Map.GetNext to the first key of a map.
- Syntax
- Parameters
- Examples
- Map.Restart(myMap)
- Resets Map.GetNext(myMap) so that the next call to it will return the first key.
- Notes
- Used to list the elements of the map. Resets so that next usage of map.getnext will retrieve first key.
- Set
- Description
- Sets the value of a map element.
- Syntax
- Parameters
- m
- k
- (string) index name of map element
- a text string or expression
- val
- value of element
- any text string or expression.
- Examples
- Map.Set(myMap,"size","large")
- Sets key "size" in myMap to string "large"
- Equivalent to myMap["size"] = "large"
- Notes
- If key k:
- already exists
- previously stored value is overwritten by val
- does not exist
- key k is created & set to value val
- Map.Length is increased by 1
- This is an alternative to square bracket syntax:
m[k]=value
- SlotsUsed
- Description
- Returns number of slots used in lookup table.
- Syntax
- Parameters
- Return Value
- len
- number of slots that have been used in m
- Examples
- Local slots = Map.SlotUsed(myMap)
- Notes
- Each key in a map is hashed to an index in the lookup table. This command returns the number of indexes that have been used in that lookup table.
- It is possible for two keys to hash to the same slot index, in which case map creates a linked list of keys and values from this lookup slot. If more than 90% of slots are used then, the initial size is too small. If the number of slots is much less than the length, then the map plugin is not doing a good job of hashing for your set of keys, meaning search time is being spent scanning linked lists.
- Map Handles
- Maps are created with the Map.Create function, which returns a handle to use in subsequent calls to the map.
- A handle takes the form of a string m-n, where n is a number.
- Handles are always greater than 0.
- MiscPlugin
- Author
- Commands
- Alphabetical
- Append_Clip
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- BalloonTip
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Count_HardLinks
- Description
- Count Hard Links (for NTFS only)
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Create_HardLink
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Date_Diff
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Date_Range
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Dim
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- ElapsedTime
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- FileInfo
- Description
- Retrieves information about a property of the file or folder in variable "sFileName".
- Syntax
- sFileName = fpath
MiscPlugin.FileInfo(property)
- Parameters
- fpath
- (string) full path to a file, including file name & extension
- property
- (string) specifies which file information to retrieve
- Some properties ("size", "foldersize" & "exif") have extra parameters.
- Possible Values
- size
- Retrieves file size in bytes.
- Optional Additional Parameters
- Example
- local sFileName = ?"c:\docs\largefile.doc"
Win.Debug( MiscPlugin.FileInfo("size:m") )
- Outputs the size of the file "largefile.doc" in megabytes.
- foldersize
- Retrieves size of a folder in bytes.
- Optional Additional Parameters
- Example
- local sFileName = ?"c:\winnt\system"
Win.Debug( MiscPlugin.fileinfo("foldersize") )
Win.Debug( MiscPlugin.fileinfo("foldersize:k") )
Win.Debug( MiscPlugin.FileInfo("foldersize:m") )
- Outputs the size of the folder "c:\winnt\system" in bytes, then kb, then mb.
- modified
- Retrieves last modified date & time.
- accessed
- Retrieves last accessed date & time.
- created
- Retrieves date & time created.
- modifieddate
- Retrieves last modified date only.
- accesseddate
- Retrieves last accessed date only.
- createddate
- modifiedtime
- Retrieves last modified time only.
- accessedtime
- Retrieves last accessed time only.
- createdtime
- attrib
- Retrieves the file attributes.
- shortname
- Retrieves the 8.3 format filename.
- unc
- Retrieves the network shared name.
- width
- Retrieves the width for .bmp, .gif, .jpg, and .png files.
- height
- Retrieves the height for .bmp, .gif, .jpg, and .png files.
- WxH
- Retrieves the width & height as "WxH", for .bmp, .gif, .jpg, and .png files.
- exif
- Exchangeable Image File format info for Jpeg
- Optional Additional Parameters
- date
- Retrieves the capture date as "yyyymmdd".
- time
- Retrieves the capture time as "hhmmss", in 24h format.
- cammake
- Retrieves the camera make or brand.
- cammodel
- Retrieves the camera model.
- flash
- Whether the flash used: 1 or 0.
- exp
- Retrieves the exposure time.
- aper
- Retrieves the aperture value.
- Example
- local sFileName = ?"c:\mypics\photos\people.jpg"
Win.Debug( MiscPlugin.FileInfo("exif", "cammake") )
- Outputs the make of camera used to photograph "people.jpg", if available.
- Return Value
- (mixed) either:
- the requested file information
- error string
- "PROP_NOT_FOUND"
- for "exif" property with jpeg files, when requested exif information is not found
- "ERROR_FILE_ACCESS"
- can't find the file, or encounter errors while accessing the file
- "ERROR_INVALID_KEYWORD"
- invalid keyword specified
- "ERROR_NOT_SHARED"
- "unc" is requested property, & the file/folder in sFileName is not shared
- "ERROR_INVALID_FILETYPE"
- "width" or "height" was requested but the file is not a valid bmp, gif, jpg, or png file
- Examples
- local sFileName = ?"c:\docs\somedoc.doc"
Win.Debug( MiscPlugin.FileInfo("createddate) )
- Outputs the date "somedoc.doc" was created.
- local sFileName = ?"c:\mypics\photos\flowers.jpg"
Win.Debug( MiscPlugin.FileInfo("exif", "date") )
- Outputs the date "flowers.jpg" was taken, if available.
- Get_Clipboard
- obsolete
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Get_IP
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Get_SystemDate
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Get_UserName
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Get_WindowText
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- GetChHandle
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- GetFocus
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- GetIndNum
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Is_ChEnable
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Is_TextInWin
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- IsXXX
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- MessageBox
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Minimize All
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- NewFile
- Description
- Syntax
- MiscPlugin.NewFile(fpathname)
- Parameters
- fpathname
- (string) path to the file, including the name & extension
- Path can be either:
- an absolute path
- relative to the PowerPro folder directory
- Return Value
- (string) either:
- "SUCCESS"
- file created successfully
- "ERROR_CREATING_FILE"
- if file already exists, or for some other reason file could not be created
- Examples
- Win.Debug( MiscPlugin.NewFile(?"c:\test.txt") )
- Creates the file "test.txt", then outputs "SUCCESS" if successful, else "ERROR_CREATING_FILE".
- ReminderUI
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- RunDialog
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Set_ActWnd
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Set_FileAttrib
- Description
- Modify the attributes of a file.
- Syntax
- sFileName = fpath
MiscPlugin.Set_FileAttrib(attribs)
- Parameters
- attribs
- (string) changes to the file attributes to be performed
- Possible Values
- Attributes are prefixed with:
- Return Value
- (string) either:
- the resulting file attributes string
- "ERROR_FILE_ACCESS"
- file not found, or errors encountered while accessing the file
- Examples
- local sFileName, sAttrib
sFileName = "D:\MiscPlugin\Release\New File.txt"
sAttrib = MiscPlugin.set_fileattrib("+A+R-H-S")
Win.Debug(sAttrib)
- Set_SystemDate
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Set_TaskBar
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- SetFocus
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Show_Menu
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Sleep
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- TempFileName
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Touch_FileTime
- Description
- Set the date and time stamp of the file specified in variable "sFileName".
- Syntax
- sFileName = fpath
sOutput = MiscPlugin.Touch_FileTime(fieldToChange, date, time)
- Parameters
- fieldToChange
- (string) the field or fields to change
- Possible Values
- "a"
- Last Accessed date/time of the file
- "c"
- Creation date/time of the file
- "m"
- Last Modified date/time of the file
- date
- (string) date as a 8-char string: "yyyymmdd"
- Optional, default is current system date.
- time
- (string) time as a 6-char string in in 24h format: "hhmmss"
- Optional, default is current system time.
- Return Value
- (string) either:
- "SUCCESS"
- date/time changed successfully
- "ERROR_FILE_ACCESS"
- couldn't find the file, or the file is read-only, or encountered errors while accessing the file
- "ERROR_INVALID_PARAMETER"
- invalid parameter specified
- Examples
- sFileName = "c:\docs\file.txt"
sOutput = MiscPlugin.Touch_FileTime("ma")
- Changes the Last Modified and Last Accessed date & time settings of the file "file.txt" to the current system date & time.
- Wait_Window
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Categorised
- Data Types
- is_int
- is_alphanum
- Alphanumeric (A – Z, a – z, or 0 – 9)
- is_alpha
- Alphabetic (A - Z or a - z)
- is_ascii
- ASCII character (0x00 – 0x7F)
- is_controlchar
- Control character (0x00 – 0x1F or 0x7F)
- is_lud
- Letter, underscore, or digit
- is_lu
- is_lowercase
- is_uppercase
- is_printable
- Printable character except space
- is_printablespace
- Printable character including space (0x20 - 0x7E)
- is_punct
- is_hexdigit
- Hexadecimal digit (A - F, a - f, or 0 - 9)
- is_wschar
- White-space character (0x09 – 0x0D or 0x20)
- Date & Time
- Date_Diff
- Date_Range
- ElapsedTime
- Get_SystemDate
- ReminderUI
- Set_SystemDate
- File
- Count_HardLinks
- Create_HardLink
- FileInfo
- Retrieves information about a file
- keywords
- size
- foldersize
- modified
- accessed
- created
- modifieddate
- accesseddate
- createddate
- modifiedtime
- accessedtime
- createdtime
- attrib
- shortname
- unc
- width
- height
- WxH
- exif
- Retrieves information about a file
- NewFile
- Create a new empty file
- sOutput = MiscPlugin.NewFile("c:\test.txt")
- result "SUCCESS" or "ERROR_CREATING_FILE"
- Set_FileAttrib
- TempFileName
- Touch_FileTime
- System
- BalloonTip
- Displays a balloon tip in the tray
- Dim
- Description
- Dims the screen
- This service will dim or darken the entire screen while still allowing user interaction.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Get_IP
- Get IP Address of a computer
- Get_UserName
- Return the user's name of the local PC or of a PC given it's IP address
- MessageBox
- Show customized message box
- RunDialog
- Set_TaskBar
- Show_Menu
- Sleep
- Get_Clipboard
- Append_Clip
- Window
- Get_WindowText
- GetChHandle
- GetFocus
- Returns the child control of the foreground window that has the focus
- GetIndNum
- Description
- This service will return the index number of a given child control's window handle.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Is_ChEnable
- Determines if a child control of a window is enabled/disabled
- Is_TextInWin
- Check if text is existing inside a window
- Minimize All
- Set_ActWnd
- SetFocus
- Wait_Window
- Net
- Author
- Alan Campbell aka entropyreduction
- Note
- Author
- Commands A-I
- AppendLine
- Description
- Adds a line to the end of a note.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- AppendText
- Description
- Appends text to the end of a note.
- Syntax
- note.appendText(nh,str)
- nh.appendText(str)
- Parameters
- nh
- (number) target note handle
- str
- Examples
- nh.AppendText("px")
- Adds the text "px" to the note's end.
- Bottom
- Description
- Returns left coordinate of note.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- CharFromLine
- Description
- Returns characters position corresponding to start of line position.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Close
- Description
- Closes and saves the specified note.
- Syntax
- Parameters
- nh
- (number) target note handle
- Examples
- Note.Close(nh)
- Closes the note whose handle is in variable "nh".
- Cycle
- Description
- Cycles though open notes, one at a time, showing them as it goes.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Delete
- Description
- Closes and deletes the specified note.
- Syntax
- Parameters
- nh
- (number) target note handle
- Examples
- local nh = Note.Open
Wait.For(3000)
Note.Delete(nh)
- Opens an empty note & assigns its handle to variable "nh", then wait for 3 seconds before deleting it.
- Find
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- GetBackColor
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- GetCaretLine
- Description
- Returns line position of text caret
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- GetCaretPos
- Description
- Returns character position of text caret
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- GetCategory
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- GetLine
- Description
- Returns a line in a note.
- Syntax
- Note.GetLine(nh, lindex)
- nh.GetLine(lindex)
- Sets strLine to the contents of line lindex (starting at line 0) for note with handle nh; remove terminating CR-LF from text.
- Parameters
- nh
- (number) target note handle
- lindex
- (number) index of the target line
- Return Value
- (string) contents of the line with index "lindex"
- Examples
- local s = nh.GetLine(4)
- Sets variable "s" to the 5th line of note, nh.
- GetSel
- Description
- Gets start and end character positions of any selected text in note.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- GetSel1
- Description
- Gets start character position of any selected text in note
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- GetSel2
- Description
- Gets end character position of any selected text in note
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- GetText
- Description
- Returns all or a selection of the characters in a note.
- Returns the characters in the note with handle nh starting at cindex1 and ending and cindex2, and including cindex2.
- Syntax
- Note.GetText(nh, cindex1, cindex2)
- nh.GetText(cindex1, cindex2)
- Parameters
- nh
- cindex1
- (number) index of first character
- Optional, default is char at index 0 (start of note).
- cindex2
- (number) index of last character
- Optional, default is the last character of note.
- Return Value
- (string) requested text of the note
- Examples
- Note.GetText(nh)
- Returns all of the text in the note of handle "nh".
- Vec.CreateFromLines(Note.GetText(nh))
- Creates a vector with each element taken from a line of the note with handle nh.
- GetTextColor
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- HandleList
- Description
- Returns a blank-separated list of handles of open notes, limited to about 55 open notes.
- Syntax
- Note.HandleList(strcat, hidden)
- Parameters
- str_cat
- (string) category name
- Possible Values
- *
- category name
- returns only notes with this category
- hidden
- (boolean)
- 1
- returns handles of both visible and hidden notes
- 0
- returns handles of visible notes only
- Return Value
- (string) blank-separated list of note handles
- Examples
- local nhList = Note.HandleList("temp", 1)
- Assigns the list of handles of all open visible & hidden notes in category "temp" to variable "nhList".
- Height
- Description
- Returns height of note in pixels.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- InsertLine
- Description
- Inserts a line into a note.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- InsertText
- Description
- Inserts some text into a note.
- Syntax
- Note.InsertText(nh, str, cindex)
- nh.InsertText(str, cindex)
- Parameters
- nh
- cindex
- (number) index of the character to insert text before
- Optional, default is char at index 0 (start of note).
- Possible Values
- 0
- omit, or cindex>length of note
- Examples
- nh.InsertText("quick brown fox", 4)
- Inserts the text "quick brown fox" before char 4.
- IsOnTop
- Description
- Returns 1 if note is ontop.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- IsRolled
- Description
- Returns 1 if note is rolled.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- IsValid
- Description
- Returns 1 if note valid note handle supplied.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- IsVisible
- Description
- Returns visibility state of note.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Commands L-W
- Length
- Description
- Returns the number of characters in a note.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- LineCount
- Description
- Returns number of lines in a note.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- LineFromChar
- Description
- Returns line index corresponding to character position.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Left
- Description
- Returns left window coordinate of Note ion pixels.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Move
- Description
- Moves note to new position
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- OnTop
- Description
- Makes a note topmost or not topmost.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Open
- Description
- Creates a new note and returns its (window) handle.
- Syntax
- Note.Open(fpath, keywords, show_flag)
- Parameters
- All of the parameters are optional.
- fpath
- (string) path to a text file or another note, containing initial text for this new note
- Optional, default is to create a new blank note.
- keywords
- (string) any combination of the following keywords, indicating initial settings for the look, position, and text of the note
- Optional.
- Possible Values
- clip
- cat C
- set note category to C
- C is the note category (in quotes)
- file F
- copy file F into note
- F is the file path (in quotes)
- pos X Y
- position at (X,Y) on the screen
- pos bottomleft
- position the note bottom left
- pos bottomright
- position the note bottom right
- pos center
- pos stack
- position the note on top of the stack
- pos topleft
- position the note top left
- pos topright
- position the note top right
- pos under
- position the note under the mouse
- settext T
- set the initial text (no spaces) to appear in the note
- T is the initial note text (in quotes)
- size W H
- set note to width W & height H
- top
- text R G B
- specifies text color as an RGB colour value of 3 integers, each between 0-255
- back R G B
- specifies background color as an RGB colour value of 3 integers, each between 0-255
- tab T
- show_flag
- (number) flag indicating whether to make note the active window
- Optional.
- Possible Values
- 2
- note is shown and activated
- omitted or 1
- note is shown but does not become the foreground window
- 0
- note is created but not shown
- Return Value
- (number) handle of the new note
- Examples
- global nh = Note.Open("", "top text 255 255 0 back 0 0 255 pos topright")
- Creates a blank note, setting its text & background colours, its position (topright), & making it topmost.
- Raise
- Description
- Cycles through open notes and removes always on top property.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- ReplaceLine
- Description
- Inserts a line into a note.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- ReplaceSel
- Description
- Replaces the selection in a note.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- ReplaceText
- Description
- Deletes the text in a note starting & ending at specific characters (inclusive), & replaces it by str.
- Syntax
- note.replaceText(nh, str, cindex1, cindex2)
- nh.replaceText( str, cindex1, cindex2)
- Parameters
- nh
- str
- (string) string to replace deleted text with
- Possible Values
- a string
- ""
- deletes the text in the note only
- cindex1
- (number) index of first character to be deleted
- cindex2
- (number) index of last character to be deleted
- Examples
- nh.ReplaceText( "quick brown fox", 3, 9)
- Replaces characters 3 to 9 inclusive in the note with handle "nh" with "quick brown fox".
- Notes
- Omit cindex1 and cindex2 to replace all text.
- If cindex1>cindex2, nothing happens.
- If cindex1>length of note, the characters are added to the end of the note.
- If cindex2 only is omitted, it is taken as the end of the note.
- Right
- Description
- Returns right coordinate of note.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Roll
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- ScrollCaret
- Description
- Scrolls note so that caret is in view.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- ScrollTo
- Description
- Scrolls to indicated line or page.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- SetBackColor
- Description
- Sets background color of note.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- SetCategory
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- SetSel
- Description
- Sets start and end of selection.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- SetTab
- Description
- Sets the tab position for the note.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- SetTextColor
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Show
- Description
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- VScroll
- Description
- Scrolls lines or pages, up or down.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- Width
- Description
- Returns width of note in pixels.
- Syntax
- Parameters
- Keywords
- Return Value
- UI Elements
- Global Variables
- Examples
- Notes
- See Also
- ODBC
- Author
- Alan Campbell aka entropyreduction
- Reg
- Author
- Alan Campbell aka entropyreduction
- Regex
- Vec
- Overview
- The vec plugin lets you work with single-dimension arrays, i.e. vectors.
- Author
- Commands
- BinIndex
- Description
- Locates position of an element in sorted array using binary search.
- If the target element does not exist, Vec.BinIndex() returns the position the element would have occurred, minus 1.
- Syntax
- Parameters
- Return Value
- (integer) index of val in v
- Examples
- local v = Vec.CreateFromWords("one Two three four Five")
Vec.Sort(v)
Win.Debug( Vec.BinIndex(v, "Two") )
Win.Debug( Vec.BinIndex(v, "six") )
- Outputs 4, the index of "Two" in v after it is sorted in ascending order, then 2, equal to the index "six" would have if it were in the array, minus 1.
- Notes
- A binary search is a method for finding a particular value in a linear array by "ruling out" half of the data at each step.
The search begins with an interval covering the whole vector, then if the value of the search term is less than the element in the middle of the interval, the interval is narrowed to the lower half, otherwise it is narrowed to the upper half.
The above process is repeated until the value is found or the interval is empty. - Vec.BinIndex() & Vec.BinSearch() are similar, except in their consideration of nonexistent elements.
- See Also
- BinInsert
- Description
- Inserts an element into a sorted array using binary search.
- Syntax
- Parameters
- v
- (integer) vector handle
- v must be sorted in ascending order.
- val
- (string or integer) value to insert
- val is only inserted into the vector v if it is not already there.
- Return Value
- (integer) index of val in v
- Examples
- global v = Vec.CreateFromWords("one two Three four Five", 5)
Vec.Sort(v)
local i = Vec.BinInsert(v, "Six")
Win.Debug( i )
Win.Debug( Vec.Makewords(v) )
- Outputs 3, the index of "Six" in the vector v after it is inserted, then "Five four one Six Three two", the vector elements concatenated into a space-separated string.
- Notes
- A binary search is a method for finding a particular value in a linear array by "ruling out" half of the data at each step.
The search begins with an interval covering the whole vector, then if the value of the search term is less than the element in the middle of the interval, the interval is narrowed to the lower half, otherwise it is narrowed to the upper half.
The above process is repeated until the value is found or the interval is empty.
- BinSearch
- Description
- Performs a binary search on a sorted vector for a value.
- Syntax
- Parameters
- v
- (integer) vector handle
- The vector v must be sorted in ascending order, ignoring case.
- val
- (string or integer) value to find
- Return Value
- (integer) either:
- i
- where i=index of element containing val
- -1
- Examples
- global v = Vec.Create(5)
v[0] = "one"
v[1] = "two"
v[2] = "Three"
v[3] = "four"
v[4] = "Five"
Vec.Sort(v)
Win.Debug( Vec.Makewords(v) )
local i = Vec.BinSearch(v, "one")
Win.Debug( i )
- Creates a 5-element vector & sorts it in ascending order, then performs a binary search for the value "Three", putting the index of the element containing "Three" (or -1 if not found) into i.
- Outputs first: "Five four one Three two", then: 2.
- Notes
- A binary search is a method for finding a particular value in a linear array by "ruling out" half of the data at each step.
The search begins with an interval covering the whole vector, then if the value of the search term is less than the element in the middle of the interval, the interval is narrowed to the lower half, otherwise it is narrowed to the upper half.
The above process is repeated until the value is found or the interval is empty.
- See Also
- Capacity
- Description
- Returns the capacity of a vector.
- Syntax
- Parameters
- Return Value
- (integer) the vector's current capacity
- Examples
- local vCap = Vec.Capacity(v)
- Assigns local variable vCap the value of the capacity of vector v.
- Notes
- Vec.Capacity() and Vec.Length() are two different things & can return different values.
- Create
- Description
- Creates a new vector and returns its handle.
- Creates a vector with specified capacity.
- Syntax
- Vec.Create(capacity, growth, minsize)
- Parameters
- capacity
- (integer) initial capacity of the vector, i.e. maximum number of elements
- The initial size of a vector should be based on how big it is going to be in most cases.
- growth
- (integer) growth factor
- Optional, default is 0.
- Possible Values
- >0
- Vector is grown automatically by the value of growth when any element with index equal to the vector's current capacity is set or inserted.
- Attempting to set or get an element with index greater than current capacity will cause an error.
- 0
- minsize
- (integer) minimum amount of memory to assign each element, in bytes
- Setting a value for minsize helps to avoid excessive calls to the system memory allocator.
- When specified, each element is allocated at least minsize bytes, and that memory is re-used whenever new values are written to the element which don't require more memory.
Only when a new value requires more space is a new larger buffer allocated, & the initial minsize bytes are then freed.
Additionally, the Vec plugin will also shrink allocated memory in some circumstances, if an element with a large allocation is re-assigned a much smaller string.
So, for example, with a minsize of 8:
vec[1] ="1234" ;; 8 bytes allocated, five used (zero byte at end)
vec[1] = "123456" ;; re-used the same 8 bytes
vec[1] = "1234567890123" ;; first 8 bytes freed, new 14 bytes buffer allocated
- Optional, default is that each element is allocated exactly as much memory as it needs when first set or when the amount of space need exceeds current capacity.
However, in this situation with minsize not set, memory is only de-allocated if the capacity is greater > 500 or so and the amount needed is less than 1/2 the capacity.
- Return Value
- (integer) the vector handle
- Examples
- global v = vec.create(50, 50)
- Creates an array of initial size 50 elements, that will grow by 50 elements every time the 50th element is set/inserted.
- Notes
- The expression:
v = vec.create(0, 1)
creates an array with 1 empty element & gives it "automatic growth", so that setting or inserting the element with index equal to v's current capacity will increase its size by 1.
This is not optimal, however, as PowerPro has to re-allocate the memory used to store the array pointers every time you add a new element. This can fragment your memory. Its better to use something like
v = vec.create(50, 50)
so that growth is in chunks rather than element by element.- Bruce, 2002-12-31, PowerPro list
- CreateFromLines
- Description
- Creates a new vector from the lines in a string and returns its handle.
- Syntax
- Vec.CreateFromLines(lines, growth, minsize)
- Parameters
- lines
- (multi-line string) contents for the vector
- Lines in "lines" are separated by "\n", "\r", or the pair "\r\n". The "\r" and/or "\n" at the end of each line is not stored.
- The resultant vector is created with one element for each line in "lines".
- growth
- (integer) growth factor
- Optional, default is 0.
- Possible Values
- >0
- Vector capacity is increased automatically by specified value whenever an element with index equal to the vector's current capacity is set or inserted.
- Attempting to set or get an element with index greater than current capacity will cause an error.
- 0
- minsize
- (integer) minimum amount of memory to assign each element, in bytes
- When specified, each element is allocated at least minsize bytes of memory, which will be re-used if a new value is written to the element which does not require more space.
- Optional.
- See Vec.Create() for more detailed information on the minsize parameter.
- Return Value
- Examples
- global v = Vec.CreateFromLines("line1\n2222\r\nthird\n\n")
- Creates a four-element vector:
v[0] = "line1"
v[1] = "2222"
v[2] = "3"
v[4] = ""
- global v = Vec.CreateFromLines(Clip.Get)
- Creates a vector with one element for each line on the clipboard.
- Note that Clip.Get is used to return the full contents of the clipboard; the built-in function "clip" only returns the first line of the clipboard.
- Notes
- The vec plugin can support at most 50 simultaneously active vectors.
- CreateFromWords
- Description
- Creates a vector with one element for each word in the specified string, & returns its handle.
- Syntax
- Vec.CreateFromWords(words, growth, minsize)
- Parameters
- words
- (string) a list of words, separated by one or more consecutive blanks, or by tabs.
- The blanks or tabs at the end of each word are not stored, they act only as word delimiters.
- growth
- (integer) growth factor
- Optional, default is 0.
- Possible Values
- >0
- Vector is grown automatically by the value of growth when any element with index equal to the vector's current capacity is set or inserted.
- Attempting to set or get an element with index greater than current capacity will cause an error.
- 0
- minsize
- (integer) minimum amount of memory to assign each element, in bytes
- When specified, each element is allocated at least minsize bytes of memory, which will be re-used if a new value is written to the element which does not require more space.
- Optional.
- See Vec.Create() for more detailed information on the minsize parameter.
- Return Value
- Examples
- global v = vec.createFromWords("line1 2222\t3")
- Creates a 3-element vector:
v[0] = "line1"
v[1] = "2222"
v[2] = "3"
- global v = vec.createFromWords(win.handleList("*",0))
- Creates a vector of all visible windows, with each element set to a visible window handle.
- Notes
- The vec plugin can support at most 50 simultaneously active vectors.
- Vec.CreateFromWords() is the opposite of Vec.MakeWords().
- Delete
- Description
- Removes an element from a vector, & moves all the following elements down one to fill up the space.
- Syntax
- Parameters
- v
- i
- (integer) index of the element to delete
- Examples
- global v = Vec.Create(3, 3)
v[0] = "one"
v[1] = "two"
v[2] = "four"
v[3] = "five"
Win.Debug(Vec.Length(v))
local res = Vec.Delete(v, 2)
Win.Debug(Vec.Length(v))
- Outputs "4", then "3", with the remaining elements being:
v[0] = "one"
v[1] = "two"
v[2] = "five"
after the element v[2] is deleted, and v[3] moved down to the now empty v[2].
- Notes
- Vec.length decreases by 1.
- DeleteAll
- Description
- Removes all the elements from a vector, leaving an empty vector.
- Syntax
- Parameters
- Examples
- global myVec = (3)
myVec[0] = "foo"
myVec[2] = "bar"
Vec.DeleteAll(myVec)
- Creates a 3-element vector, myVec, sets 2 of the elements, then deletes them all.
- Notes
- The target vector's length is set to 0.
- Destroy
- Description
- Frees all memory assigned to v and its elements, then frees the handle for use by another vector.
- Syntax
- Parameters
- Return Value
- (integer) Returns 0 which you can assign to v to indicate that v is no longer a valid vector.
- Examples
- global v = vec.create(10,10)
v = Vec.Destroy(v)
- Creates a 10-element growable vector & assigns its handle to v, then destroys it, setting v to 0.
- Notes
- See "Vec Plugin > Multidimensional Arrays > Destroying Multidimensional Arrays" for info on destroying multidimensional arrays, which are not completely destroyed by a single Vec.Destroy(v) call & must be manually destroyed.
- DoubleSort
- Description
- Sorts one vector in ascending or descending order, keeping the elements of a 2nd vector in a corresponding order.
- Syntax
- Vec.DoubleSort(v, w, flagsort, flagcase)
- Parameters
- v
- (integer) handle of the vector to be sorted
- w
- (integer) handle of the vector whose elements will be kept in corresponding order to v
- So, w[1] will move to the same position as v[1], w[2] will move to the same position as v[2], etc.
- flagsort
- (boolean) sort order
- Optional, default is 0.
- Possible Values
- flagcase
- (boolean) case-sensitivity
- Optional, default is 0.
- Possible Values
- Examples
- global v, w
v = Vec.CreateFromWords("300 136824 4 22")
w = Vec.CreateFromWords("Q a t X")
Vec.DoubleSort(v, w)
Win.Debug( Vec.MakeWords(v) )
Win.Debug( Vec.MakeWords(w) )
- Outputs first: "4 22 300 136824" for v, then: "t X Q a" for w, as w's elements have been sorted as v's have (ignoring the actual values of elements in w).
- Notes
- Strings of 9 digits or less (in the first vector) are treated as numbers for comparisons, so that "4" is less than "20".
- For strings of 10 characters or more in the first vector whose first 9 characters are numbers, only those first 9 digits are considered for the comparison.
- DoubleSortString
- Description
- Sorts one vector in ascending or descending order, keeping the elements of a 2nd vector in a corresponding order.
- This service is similar to Vec.DoubleSortString(), except that here, the contents of the sorted vector are always treated as string. E.g, "4" is greater than "20".
- Syntax
- Vec.DoubleSortString(v, w, flagsort, flagcase))
- Parameters
- v
- (integer) handle of the vector to be sorted
- w
- (integer) handle of the vector whose elements will be kept in corresponding order to v
- So, w[1] will move to the same position as v[1], w[2] will move to the same position as v[2], etc.
- flagsort
- (boolean) sort order
- Optional, default is 0.
- Possible Values
- flagcase
- (boolean) case-sensitivity
- Optional, default is 0.
- Possible Values
- Examples
- global v, w
v = Vec.CreateFromWords("300 136824 4 22")
w = Vec.CreateFromWords("Q a t X")
Vec.DoubleSortString(v, w)
Win.Debug( Vec.MakeWords(v) )
Win.Debug( Vec.MakeWords(w) )
- Outputs first: "136824 22 300 4" for v, then: "a X Q t" for w, as w's elements have been sorted as v's have (ignoring the actual values of elements in w).
- Each value in v was compared as if it was a string, not a number.
- Exists
- Description
- Checks if a vector exists.
- Syntax
- Parameters
- Return Value
- Examples
- global v = Vec.Create(10,10)
Win.Debug( Vec.Exists(v) )
v = Vec.Destroy(v)
Win.Debug( Vec.Exists(v) )
- Creates a 10-element vector, tests the vector handle's validity (outputting "1"), destroys the vector, & retests the handle, outputting "0".
- Get
- Description
- Retrieves the value of the specified element.
- Syntax
- Parameters
- v
- i
- (integer) index of the element to retrieve
- Any expression can be used for i.
- Return Value
- (string) value of the element
- Examples
- local sNm = Vec.Get(vNames, 0)
- Retrieves the value of the first element of the vector vNames, & assigns it to the local variable sNm.
Note that the equivalent square bracket syntax is generally easier:
local sNm = vNames[0]
- Notes
- Equivalent to the square bracket syntax form:
s = v[x]
which would retrieve the value of the ith element of the vector v.
- Grow
- Description
- Increases the capacity of a vector by a specified number of elements.
- Syntax
- Parameters
- v
- growth
- (integer) number of extra elements to allow in vector v
- Examples
- global v = Vec.CreateFromWords("one two three")
Vec.Grow(v, 3)
Win.Debug(Vec.Capacity(v))
Win.Debug(Vec.Length(v))
- Creates a 3-element vector then increases its capacity by 3 with the Vec.Grow() call.
The output from the last 2 lines would be "6", for the capacity, then "3", for the vector's length, as there are still only 3 elements in it, despite the capacity growth.
- Notes
- Vec.Length() is not affected by a Vec.Grow() call.
- Insert
- Description
- Inserts a new element in a vector by moving other elements along one.
- Syntax
- Parameters
- v
- i
- (integer) index of the element
- Indexes i<0 or i>vec.capacity are in error and will elicit an error message from vec
- s
- (string) value to insert at v[i]
- Examples
- global v = Vec.Create(3, 3)
v[0] = "one"
v[1] = "two"
v[2] = "four"
v[3] = "five"
Vec.Insert(v, 2, "three")
for (local i=0; i<4; i=i+1)
Win.Debug(i++":", v[i])
endfor
- Creates a 4-element vector v, setting the values of all its elements, then inserts the string "three" at index 2. The vector v would now contain:
v[0] = "one"
v[1] = "two"
v[2] = "three"
v[3] = "four"
v[4] = "five"
and Vec.Length() would return 5.
- Vec.Insert(v, 2, "quick brown fox")
- Inserts the string "quick brown fox" into v[2], moving the value that was at v[2] to v[3], & so on.
- Notes
- Vec.Length() increases by 1 after a Vec.Insert() call.
- If the vector is already at capacity and the growth is > 0, then vec will grow the vector by growth elements to accomodate the new element.
- InsertNoGrow
- Description
- Inserts new element at specified index in vector & moves other elements along, deleting the last element if Vec.Length==Vec.Capacity.
- Syntax
- Vec.InsertNoGrow(v, i, s)
- Parameters
- v
- i
- (integer) index of the element to insert new value at
- s
- (string) string expression to insert
- Examples
- Vec.InsertNoGrow(v, 2, "quick brown fox")
- Inserts the string quick brown fox into v[2], pushing the value at v[2] into v[3], and so on, until the last element, which is deleted if there are no more spots available.
- Notes
- If the Vec.Length() < Vec.Capacity(), it increases by one; otherwise, the last element in the vector is deleted.
- Length
- Description
- Retrieves the length of a vector.
- Syntax
- Parameters
- Return Value
- (integer) highest occupied index of vector v
- Examples
- global v = Vec.Create(10, 10)
Win.Debug( Vec.Length(v) )
v[6] = "quick brown fox"
Win.Debug( Vec.Length(v) )
- Creates a 10-element vector then sets the seventh element, meaning the 2 Vec.Length() calls output first "0", then "7". The other elements of v (elements 0-6) are set to "" (an empty string).
- Notes
- Note that Vec.Length() and Vec.Capacity() are different.
- LocalCopy
- Description
- Creates a local copy of a vector that has been passed as an argument.
- Syntax
- Parameters
- n
- (integer) function argument number
- 1 =< n =< 9
- Return Value
- Examples
- local v = Vec.LocalCopy(arg(1))
- Notes
- This service must be used when creating local variable with reference to vectors that have been passed as arguments.
Assigning the passed vector directly to a local variable means it will be destroyed when the local routine exits:
; WRONG
local v = arg(1)
Instead, using Vec.LocalCopy(), a reference to the vector is created locally, & only this is destroyed when the routine finishes.
; RIGHT
local v = Vec.LocalCopy(arg(1))
- MakeLines
- Description
- Makes a multi-line string from the elements of a vector.
- Syntax
- Parameters
- Return Value
- (multi-line string) elements of v are now separate lines of the resultant string, with "\r\n" between each line
- Examples
- local v = Vec.CreateFromWords("one Two three four Five")
Win.Debug( pickstring( Vec.MakeLines(v), "Pick one:") )
- Shows a selection dialog with the items made up from elements of v, & outputs the selected value to a debug window.
- MakeWords
- Description
- Makes a single, space-separated string of words from the elements a vector.
- Syntax
- Parameters
- Return Value
- (string) one or more space-separated strings
- Examples
- local v = Vec.CreateFromWords("one Two three four Five")
Vec.Sort(v, 1, 1)
Win.Debug( Vec.MakeWords(v) )
- Creates a 5-element vector, performs a case-sensitive sort on it in descending order, then uses Vec.MakeWords() to turn it back into a single string with spaces.
- Outputs:
three one four Two Five
- Notes
- Vec.MakeWords() is the opposite of Vec.CreateFromWords().
- MaxVecs
- Description
- Increases the maximum number of vectors allowed in PowerPro.
- Syntax
- Parameters
- n
- (integer) new maximum number of vectors
- n must be greater than the current maximum number of vectors
- Return Value
- Examples
- local i = Vec.MaxVecs(60)
if (i) do
Win.Debug("Maximum number of vectors changed to 60")
else
Win.Debug("Could not change maximum number of active vectors")
endif
- Raises the number of vectors allowed in PowerPro to 60 and outputs a message of success or failure as appropriate.
- Notes
- Can be called at any time; existing vectors are preserved.
- Set
- Description
- Sets a vector element, overwriting any previously set value at that index.
- Syntax
- Parameters
- v
- i
- (integer) index of the element to set
- Indexes start at zero.
- Possible Values
- i >= Vec.Length
- vector length is assigned i+1.
- i == Vec.Capacity
- If vec's growth value is greater than 0, then the vector will grow by the number of elements set in the original vector creation call, in order to accomodate the new element.
- i<0, i>Vec.Capacity
- such indexes are in error and will elicit an error message.
- s
- (mixed) value to assign to element i
- Examples
- global v = Vec.Create(3, 3)
Vec.Set(v, 0, win.caption("active"))
Vec.Set(v, 1, 3729)
Vec.Set(v, 2, "quick brown fox")
Vec.Set(v, 3, win.ontop("active"))
Win.Debug( Vec.Capacity(v) )
- Creates a 3-element vector with a growth value of 3, then sets 4 elements. When the 4th element (v[3]) is set, the capacity of v is increased by another 3 elements, so the final statement outputs "6".
- Notes
- Equivalent to the square bracket syntax form:
v[i] = s
The above would assign the value of s to the ith element of vector v. - As mentioned in the parameter definition above, indexes start at zero, which is different to the built-in line() and word() functions that both start element indexes at 1.
- ShowMenu
- Description
- Shows a menu built from the elements of a vector.
- Syntax
- Vec.ShowMenu(v, maxtext, pos, autoclose, "r g b")
- Vec.ShowMenu(v, maxtext, pos, autoclose, r, g, b)
- Parameters
- v
- (integer) handle of the vector containing the elements that are to become the menu
- The following keywords may be used as vector element values to add menu formatting:
(Note that formatting items cannot be selected from the menu, but are still considered valid vector elements with index numbers.)- *sep
- to show a horizontal menu separator
- *colsep
- *colsepline
- to start a new column with a separating line
- maxtext
- (integer) maximum number of characters in a menu item label
- Optional, default is 0 (no limit).
- Possible Values
- n
- where n=maximum length of menu label
- 0
- pos
- (integer) position of menu
- Optional, default is 0.
- Possible Values
- 0
- menu is shown at the mouse
- 1
- menu is centered on the screen
- 2
- menu is centered under the mouse
- autoclose
- (boolean) whether menu remains open or closes when the mouse is moved off it
- Optional, default is 0.
- Possible Values
- 1
- menu is closed after a few seconds if mouse moved off
- 0
- menu stays open until either a selection is made, or menu is cancelled by user
- r, g, b
- (mixed) background colour of the menu, specified as either:
- a string containing 3 space-separated values
- 3 comma-separated values
- Each value must be between 0 & 255.
- Optional.
- Return Value
- (integer) either:
- i
- where i=index of the selected entry
- -1
- if the menu is dismissed without an entry being selected
- Examples
- global v = Vec.CreateFromWords("one *sep two three *colsepline four five *sep six")
local c = Vec.ShowMenu(v, 0, 2, 1)
- Shows a 2-column menu centered under the mouse, & puts the index number of the selected element into local variable c (or -1 if menu cancelled).
- Vec.ShowMenu(Vec.CreateFromWords("one two three"),0,0,0,"255 255 255")
- Shows a menu with a white background.
- Sort
- Description
- Sorts a vector, treating strings of up to 9 digits as numbers.
- Syntax
- Vec.Sort(v, flagsort, flagcase)
- Parameters
- v
- (integer) handle of the vector to be sorted
- flagsort
- (boolean) sort order
- Optional, default is 0.
- Possible Values
- flagcase
- (boolean) case-sensitivity
- Optional, default is 0.
- Possible Values
- Examples
- Vec.Sort(myVec, 1)
- Sorts vector myVec in descending order, ignoring letter case in comparisons.
- Vec.Sort(myVec, 0, 1)
- Sorts vector myVec in ascending order, using letter case in comparisons so that "a" is greater than "A".
- global v = Vec.CreateFromWords("29734 4 23 40234789 2288")
Vec.Sort(v)
Win.Debug( Vec.MakeWords(v) )
- Yields: 4 23 2288 29734 40234789
- Notes
- Elements containing a string of 9 digits or less are treated as numbers for comparisons, so that:
global v = Vec.CreateFromWords("29734 4 40234789 23")
Vec.Sort(v)
Win.Debug( Vec.MakeWords(v) )
outputs:
4 23 2288 29734 40234789. - For strings of 9 characters or more whose first 9 characters are numbers, only those first 9 digits are considered for the comparison.
- SortString
- Description
- Sorts a vector, treating all elements, including numbers, as strings.
- Syntax
- Vec.SortString(v, flagsort, flagcase)
- Parameters
- v
- (integer) handle of the vector to be sorted
- flagsort
- (boolean) sort order
- Optional, default is 0.
- Possible Values
- flagcase
- (boolean) case-sensitivity
- Optional, default is 0.
- Possible Values
- Examples
- global v = Vec.CreateFromWords("29734 9 23 40234789 2288")
Vec.Sort(v)
Win.Debug( Vec.MakeWords(v) )
- Yields: 2288 23 29734 40234789 9
- Notes
- Elements containing numbers are always treated as strings, so that, in ascending order, "20" would always come before "4".
- Swap
- Description
- Exchanges two elements of a vector.
- Syntax
- Parameters
- v
- i
- (integer) index of the first element
- j
- (integer) index of the second element
- Examples
- Vec.Swap(myVec, 3, 5)
- Swaps the fourth & sixth elements of the vector, myVec.
- Notes
- Vec.Swap() makes more effecient use of memory than if the swap is programmed manually.
i.e. Use Vec.Swap() instead of:
temp = v[i]
v[i] = v[j]
v[j] = temp
- Multidimensional Vectors
- Creating Multidimensional Vectors
- Multidimensional vectors are possible as follows:
local v = vec.create(3)
v[0] = vec.create(10)
v[1] = vec.create(10)
v[2] = vec.create(10)
The above creates an array of 3x10.
- Destroying Multidimensional Vectors
- Multidimensional vectors must be destroyed manually to free their memory.
So, to destroy the multidimensional vector created by:
local v=vec.create(10)
v[0]=vec.create(100)
v[1]=vec.create(100)
v[2]=vec.create(100)
each inner vector must be individually destroyed before the main one:
vec.destroy(v[0])
vec.destroy(v[1])
vec.destroy(v[2])
vec.destroy(v)
- from: gmane http://thread.gmane.org/gmane.comp.windows.power-pro/8529
- Win
- Author
- Overview
- The Win plugin has various services allowing you to retrieve window or child window information, manipulate windows, send window messages, play system sounds, access certain system information, send keys, or use PowerPro's debug function.
- Commands
- Commands QuickRef: alpha-order
- area(x,y)
- Returns window area (eg client, caption, max button) under screen position x,y;
e.g. win.area(xmouse, ymouse) looks at window under mouse.
- The complete list of strings which can be returned is:
- BORDER
- In the border of a window that does not have a sizing border.
- BOTTOM
- In the lower horizontal border of the window.
- BOTTOMLEFT
- In the lower-left corner of the window border.
- BOTTOMRIGHT
- In the lower-right corner of the window border.
- CAPTION
- CLIENT
- CLOSE
- GROWBOX
- HSCROLL
- In the horizontal scroll bar.
- LEFT
- In the left border of the window.
- MAXBUTTON
- MENU
- MINBUTTON
- NOWHERE
- On the screen background or on a dividing line between windows.
- REDUCE
- RIGHT
- In the right border of the window.
- SYSMENU
- In a Control menu or in a Close button in a child window.
- TOP
- In the upper horizontal border of the window.
- TOPLEFT
- In the upper-left corner of the window border.
- TOPRIGHT
- In the upper-right corner of the window border.
- TRANSPARENT
- In a window currently covered by another window.
- VSCROLL
- In the vertical scroll bar.
- beep(freq, dur)
- uses internal speaker to produce tone at frequency freq for dur milliseconds
- bottom(cl)
- returns bottom window coordinate of first window matching cl
- caption(cl)
- returns window caption of first window matching cl
- childhandlelist(cl, "text")
- return blank separate list of child window handles for main window matching cl.
- Omit "text" for all.
- Set "text" to "c=classname" for only those child windows of class classname.
- If text is anything else, only windows with window text matching text are retrieved.
- childtextbyindex(cl,n)
- returns the text in the nth childwindow of first window matching cl.
- If there are less than n child windows, sets variable _EOF_ to 1; else sets _EOF_ to 0. First looks for visible windows matching cl; if none, tries hidden windows matching cl.
- class(cl)
- returns window class of first window matching cl
- close(cl)
- closes first window matching cl
- closeforce(cl)
- closes first window matching cl, unsaved information is lost
- debug(sz1, sz2)
- up to 6 arguments can be specified; they are joined and shown in a debug window.
- dropfile(cl, filepath)
- simulates drag and drop of file name onto first window matching cl. Does not work for all programs.
- enable(cl,flag)
- enables window matching cl if flag is anystring not starting with "0"; disables otherwise
- hex(n)
- returns hexadecimal equivalent for n
- enabled(cl)
- returns 1 if first window matching cl is enabled, 0 otherwise
- exepath(cl)
- returns full path to exe of first window matching cl
- exename(cl)
- returns exe name (no file extension)of exe of first window matching cl
- exists(han)
- returns 1 if han is a valid window handle (may be a child window); 0 otherwise
- fullscreen()
- returns 1 if foreground window is full screen; 0 otherwise.
- fullscreen(1)
- returns 1 if any window of the same process as the foreground window is full screen.
- getdesktopname()
- returns name of Windows desktop; returns "" if desktop cannot be opened
- getfocus()
- returns handle of window with focus; may be a child window
- getpixel(x,y)
- return red, green, blue pixel at screen position x, y where (0,0) is top left. Returned as three separate numbers. Use word function to access: word(win.getpixel(100,200),2) returns blue value at screen position 100, 200;
- getpixel1(x,y)
- return red, green, blue pixel at screen position x, y where (0,0) is top left. Returned as a single number.
- getprinters()
- returns multi-line string with one printer per line
- getprocessid(han)
- returns the process id of the process for the window with handle han
- getsystemmetrics(string)
- gettext(han)
- issues WM_GETTEXT to window with handle han; the receiving window may return its text
- getworkarea()
- returns the screen work area as four blank separated integers: left, right, top, bottom
- getworkingdir(cl)
- gets working directory of window matching cl
- handlefrompoint(x,y)
- returns window handle ofwindow at under screen position x,y
- handlelist(cl, inv)
- return blank separate list of window handles matching cl.
- Set inv to 1 to include hidden windows.
- Set inv to 2 to include hidden windows, excepting those with blank captions.
- handle(cl)
- returns window handle of first window matching cl
- handle(cl,"text")
- returns handle of child window contain text of first window matching cl
- hascaption(cl)
- return 1 if first window matching cl has a caption, 2 if toolbar caption, 0 otherwise. Omit han for foreground window.
- height(cl)
- returns height of first window matching cl
- hide(cl)
- hides first visible window matching cl
- keys(sz)
- sends keys in string sz to active window (same as sendkeys)
- left
- returns left window coordinate of first window matching cl
- left(cl)
- mainhandlefrompoint(x,y)
- returns window handle of main (parent) window at under screen position x,y
- maxable(cl)
- returns 1 if first window matching cl has maximize box, 0 otherwise
- maximize(cl)
- maximizes first visible window matching cl
- maxxed(cl)
- returns 1 if first window matching cl is maximized, 0 otherwise
- message(message, title)
- messagebeep("type")
- produces system sound; set "type" to one of "ok", "hand", "exclamation", "question"
- minable(cl)
- returns 1 if first window matching cl has minimize box, 0 otherwise
- minimize(cl)
- minimizes first visible window matching cl
- minned(cl)
- returns 1 if first window matching cl is minimized, 0 otherwise
- move(cl,x,y)
- moves first visible window matching cl to position x, y;
- ontop(cl)
- makes first window matching cl topmost; removes topmost if it already is
- ontop(cl,flag)
- if flag is 0, makes window not topmost; if 1, makes it topmost; else reverses state
- parent(han)
- returns the parent of the window with handle han
- postmessage(han, msg, wp, lp)
- posts message msg to window with handle han
- resetfocus
- if PowerPro bar or Taskbar icon is foreground, makes previous window the foreground
- resizable(cl)
- returns 1 if first window matching cl is resizable, 0 otherwise
- restore(cl)
- restore first visible window matching cl
- right(cl)
- returns right window coordinate of first window matching cl
- rolled(cl)
- returns 1 if first window matching cl is rolled-up, 0 otherwise
- rollup(cl)
- rolls up window matching cl; unrolls if already is rolled up
- sendcopydata(han, dword, string)
- sends wm_copydata to window han, with dwdata=dword and lpdata=string
- sendkeys(sz)
- sends keys in string sz to active window
- sendmessage(han, msg, wp, lp)
- sends message msg to window with handle han
- sendmessagestr(han,msg,wp."string")
- sends message msg to window with handle han; lp is set to point to "string"
- setworkarea()
- sets screen work area to full size of physical screen
- setworkarea(words)
- sets the work area according to the four blanks-separated integers in words: left, right, top, bottom
- setworkarea(left,right,top,bottom)
- sets the screen work area
- setdebug(n)
- if n is 0, pauses debug output. If n is one, resumes. If n is omitted, returned current setting.
- setdefaultprinter("printer")
- sets default printer; returns 1 if successful, 0 otherwise. Only for W2000 and later.
- setfocus(han)
- sets focus and foreground to window with handle han; may be a child window
- settext(cl, "newtext")
- Issues WM_SETTEXT which may set the text of the window matching cl to newtext.
- cl could be a handle retrieved by handle(cl) for main windows or handle(cl,"text") for child windows
- setworkingdir(path)
- sets PowerPro working directory
- show(cl)
- shows first window matching cl.
- Uses PowerPro internal window activiation process unless second argument present and set to 1 for restore if icon and show, 2 ignore icon state, just show; 3: set foreground only.
- showna(cl)
- shows the window matching cl but does not activate it
- size(cl,x,y)
- sizes first visible window mathcing cl to size x,y
- toolwindow(cl)
- returns 1 if first window matching cl is toolwindow, 0 otherwise
- top(cl)
- returns top window coordinate of first window matching cl
- topmost(cl)
- returns 1 if first window matching cl is topmost, 0 otherwise
- trans(cl,num)
- makes window matching cl transparent num, num<=255. If num negative, reverses transparency state.
- transmouse(cl,num)
- makes window matching cl transparent, num<=255. Mouse clicks go through window as well. If num negative, reverses transparency state.
- traymin(cl)
- tray minimizes first window matching cl; un tray mins if already is
- trayminned(cl)
- returns 1 if first window matching cl is tray-minned, 0 otherwise
- visible(cl)
- returns 1 if first window matching cl exists, 0 if hidden exists, empty string otherwise
- width(cl)
- returns width first window matching cl
- Commands by Category
- Debug
- Debug
- Description
- Output a message to a debug window.
- Syntax
- Parameters
- sz1,...,sz6
- up to six comma-separated arguments
- Accepted Values
- Examples
- Win.Debug("Date: ", formatdate ("d/M/yy",date))
- Outputs "Date: 4/10/05" (or whatever date it is)
- Notes
- Up to 6 arguments can be specified; they are joined and shown in a debug window.
- SetDebug
- Description
- Toggles debug output or returns current setting
- Syntax
- Parameters
- Return Value
- Examples
- Win.SetDebug(0)
- Win.SetDebug()
- returns current setting for debugging, whether output is running or not
- Dialogs
- Message
- Description
- Syntax
- Win.Message(message, title)
- Parameters
- message
- (string) main text of the messagebox
- title
- (string) text to appear in the titlebar of the messagebox
- Examples
- Win.Message("Have a nice day!", "Greetings")
- See Also
- The built-in function "messagebox".
- Input dialogs.
- Desktop
- GetDesktopName
- Description
- Returns name of Windows desktop, or an empty string if the desktop cannot be opened.
- Syntax
- Return Value
- (string) either:
- desktop name
- "" (empty string)
- Examples
- Win.Debug("desktop name:", Win.GetDesktopName)
- GetWorkArea
- Description
- Returns the screen work area as four blank-separated integers: left, top, right, bottom.
- Syntax
- Return Value
- (string) 4 blank-separated values representing left, top, right & bottom
- Examples
- Win.Debug( Win.GetWorkArea )
- Outputs the current work area setting, e.g. "0 0 1024 740".
- Notes
- The screen work area is the full screen minus the Windows task bar.
- SetWorkArea
- Description
- Sets the screen work area either to the full screen, or using the specified values for left, top, right & bottom.
- Syntax
- Parameters
- sVals
- (string) 4 blank-separated valules: "left top right bottom"
- If omitted, the screen work area is set to the full screen area.
- Examples
- Win.SetWorkArea("0 0 1024 750")
- Sets screen work area to area with top left coordinate (0,0) and bottom right coordinate (1024, 750).
- Win.SetWorkArea
- Sets screen work area to the full screen area.
- Notes
- The screen work area is the full screen minus the Windows task bar.
- See Also
- PPSR > Built-in Commands > Desktop
- Hex Calculations
- Hex
- Description
- Calculates the hexadecimal equivalent of a number.
- Syntax
- Parameters
- Return Value
- (hex) a hexadecimal number
- Examples
- Win.Debug( Win.Hex(30) )
- Win.Debug( Win.Hex(inputcolor) )
- Shows a color selection dialog, then outputs the hex color value of the color selected by user.
- Keyboard & Mouse
- Keys
- Description
- Sends the keys in string keys_expr to the specified window.
- Syntax
- Win.Keys("[{target_window_string}][keys_expr]")
- Parameters
- keys_expr
- (string) the keys to send, optionally preceded by a target window string
- Possible Values
- For information on target window codes, modifiers & key codes, see:
- PPSR > Built-in Commands > Keys
- Examples
- Win.Keys("{to *metapad}abc")
- Sends the keys "abc" to Metapad.
- Notes
- Win.Keys() is essentially the same as Win.SendKeys(), but uses a different method for sending the keys.
- see Built-In Commands > Keys for details of accepted shortcuts & keywords.
- See Also
- Keywords & accepted values for the keys_expr parameters
- PPSR > Built-in Commands > Keys
- Win.SendKeys()
- An alternative method of sending text, Clip.SetPaste()
- PPSR > Plugins > Bruce's > Clip > SetPaste
- SendKeys
- Description
- Sends the keys in string keys_expr to the active window.
- Syntax
- Win.SendKeys("[{target_window_string}][keys_expr]")
- Parameters
- keys_expr
- (string) the keys to send, optionally preceded by a target window string
- Keywords & accepted formats:
- PPSR > Built-in Commands > Keys
- Examples
- Win.SendKeys("{to *metapad}abc")
- Sends the keys "abc" to Metapad.
- Notes
- Win.SendKeys() is essentially the same as Win.Keys(), but uses a different method for sending the keys.
- See Also
- Win.Keys()
- PPSR > Built-in Commands > Keys
- Mouse
- Description
- Performs mouse actions according to provided mouse code string.
- Syntax
- Parameters
- mouse_codes
- see:
- PPSR > Built-in Commands > Mouse
- Examples
- Win.Mouse("ab 100 30 lc")
- Moves the mouse to screen position (100,30), then left-click.
- Win.Mouse("al rc al")
- Performs a Shift-right-click.
- See Also
- Full listing of mouse codes at:
- PPSR > Built-in Commands > Mouse
- PowerPro
- SetWorkingDir
- Description
- Sets PowerPro's working directory.
- Syntax
- Parameters
- path
- (string) path to the new working directory
- Examples
- Win.SetWorkingDir("c:/dev/")
- Sets PowerPro's working directory to "c:\dev\".
- Run a File
- DropFile
- Description
- Simulates the drag & drop of specified file onto first window matching specified caption list.
- Syntax
- Win.DropFile(cl, filepath)
- Parameters
- cl
- filepath
- (string) path to the file to drag & drop
- Examples
- Win.DropFile("new file*", _file_)
- Drops the selected file onto the first window found matching caption list "new file*".
- Notes
- Does not work for all programs.
- Sounds
- Beep
- Description
- Uses the computer's internal speaker to produce a tone at specified frequency & duration.
- Syntax
- Parameters
- freq
- dur
- (integer) duration in milliseconds
- Examples
- if (_LastError_ != "")
Win.Beep(1000, 50)
- MessageBeep
- Description
- Syntax
- Parameters
- type
- (string) type of sound to produce
- Possible Values
- "exclamation"
- "hand"
- "question"
- "ok"
- Examples
- Win.MessageBeep("ok")
- Win.MessageBeep("question")
- System
- GetPrinters
- Description
- Retrieves a list of printers.
- Syntax
- Return Value
- (multi-line string) one printer per line
- Examples
- Win.GetPrinters
- local s = Win.GetPrinters
for (local i=1; i<line(s,0)+1; i=i+1)
Win.Debug(line(s,i))
endfor
- Outputs the name of each printer accessible by this computer, one printer per debug line.
- GetSystemMetrics
- Description
- Retrieves info about desktops & monitors.
- Syntax
- Win.GetSystemMetrics(val)
- Parameters
- val
- (string or integer) the information being sought, passed as a constant name string or integer value
- Possible Values, in alpha-order
- SM_A to SM_CX
- SM_ARRANGE
- SM_CLEANBOOT
- SM_CMONITORS
- 80
- number of monitors attached to the desktop
- SM_CMOUSEBUTTONS
- SM_CXBORDER
- SM_CXCURSOR
- 13
- same for all device drivers
- SM_CXDLGFRAME
- SM_CXDOUBLECLK
- SM_CXDRAG
- SM_CXEDGE
- SM_CXFIXEDFRAME
- SM_CXFOCUSBORDER
- SM_CXFRAME
- SM_CXFULLSCREEN
- SM_CXHSCROLL
- SM_CXHTHUMB
- SM_CXICON
- 11
- same for all device drivers
- SM_CXICONSPACING
- SM_CXMAXIMIZED
- SM_CXMAXTRACK
- 59
- maximum width of entire desktop
- SM_CXMENUCHECK
- SM_CXMENUSIZE
- SM_CXMIN
- SM_CXMINIMIZED
- SM_CXMINSPACING
- SM_CXMINTRACK
- SM_CXSCREEN
- SM_CXSIZE
- SM_CXSIZEFRAME
- SM_CXSMICON
- SM_CXSMSIZE
- SM_CXVIRTUALSCREEN
- 78
- vertical measurement of the virtual screen
- SM_CXVSCROLL
- SM_CY
- SM_CYBORDER
- SM_CYCAPTION
- SM_CYCURSOR
- 14
- same for all device drivers
- SM_CYDLGFRAME
- SM_CYDOUBLECLK
- SM_CYDRAG
- SM_CYEDGE
- SM_CYFIXEDFRAME
- SM_CYFOCUSBORDER
- SM_CYFRAME
- SM_CYFULLSCREEN
- SM_CYHSCROLL
- SM_CYICON
- 12
- same for all device drivers
- SM_CYICONSPACING
- SM_CYKANJIWINDOW
- SM_CYMAXIMIZED
- SM_CYMAXTRACK
- 60
- maximum height of entire desktop
- SM_CYMENU
- SM_CYMENUCHECK
- SM_CYMENUSIZE
- SM_CYMIN
- SM_CYMINIMIZED
- SM_CYMINSPACING
- SM_CYMINTRACK
- SM_CYSCREEN
- SM_CYSIZE
- SM_CYSIZEFRAME
- SM_CYSMCAPTION
- SM_CYSMICON
- SM_CYSMSIZE
- SM_CYVIRTUALSCREEN
- 79
- horizontal measurement of the virtual screen
- SM_CYVSCROLL
- SM_CYVTHUMB
- SM_D - SM_Y
- SM_DBCSENABLED
- SM_DEBUG
- SM_IMMENABLED
- SM_MEDIACENTER
- SM_MENUDROPALIGNMENT
- SM_MIDEASTENABLED
- SM_MOUSEPRESENT
- SM_MOUSEWHEELPRESENT
- SM_NETWORK
- SM_PENWINDOWS
- SM_REMOTECONTROL
- SM_REMOTESESSION
- SM_SAMEDISPLAYFORMAT
- SM_SECURE
- SM_SERVERR2
- SM_SHOWSOUNDS
- SM_SHUTTINGDOWN
- SM_SLOWMACHINE
- SM_SWAPBUTTON
- SM_TABLETPC
- SM_XVIRTUALSCREEN
- SM_YVIRTUALSCREEN
- LOGPIXELSX
- LOGPIXELSY
- DESKTOPHORZRES
- DESKTOPVERTRES
- SM_XVIRTUALSCREEN
- returns upper-left corner of the virtual screen
- SM_YVIRTUALSCREEN
- returns upper-left corner of the virtual screen
- SM_SAMEDISPLAYFORMAT
- whether all the monitors on the desktop have the same color format
- Return Value
- (integer) the information requested
- Examples
- Win.Debug("The cursor is", Win.GetSystemMetrics("SM_CXCURSOR"), "by", Win.GetSystemMetrics("SM_CXCURSOR"), "pixels.")
- Outputs:
The cursor is 32 by 32 pixels.
or as appropriate for the calling system.
- Notes
- All returned values are in pixels.
- All SM_CX values are widths, and all SM_CY values are heights.
- For more information, see MSDN online:
http://msdn.microsoft.com/library/en-us/sysinfo/base/getsystemmetrics.asp
- SetDefaultPrinter
- Description
- Sets the default printer. Only for W2000 and later.
- Syntax
- Win.SetDefaultPrinter(sPrinter)
- Parameters
- Return Value
- Examples
- if (not Win.SetDefaultPrinter("EPSON Stylus Photo 810 Series"))
messagebox("error", "Could not set default printer.", "Error")
- Windows
- Get Window Information
- Caption
- Caption
- Description
- Retrieves the window caption of the first window matching specified caption list.
- Syntax
- Parameters
- cl
- (cl) caption list to match
- Return Value
- Examples
- Win.Debug(Win.Caption("=metapad"))
- Outputs the caption of the first Metapad window found.
- Class
- Class
- Description
- Retrieves the window class of the first window matching specified caption list.
- Syntax
- Parameters
- cl
- (cl) caption list to match
- Return Value
- (string) class of the matching window
- Examples
- Win.Debug(Win.Class("*ppsr*"))
- Outputs the class of window that the first window with a caption like "*ppsr*".
- Color
- GetPixel
- Description
- Returns red, green & blue color values at screen position x, y where (0,0) is top left.
- Syntax
- Parameters
- Return Value
- "r g b"
- (string) the rgb color value at screen position (x,y) as 3 space-separated numbers:
- r
- g
- green color value
- 0<=g<=255
- b
- blue color value
- 0<=b<=255
- Examples
- local pxlCol = Win.GetPixel(50,100)
- Puts RGB color value of the pixel at 50, 100 into variable "cpt".
- Local mx, my, c, h
mx = xmouse
my = ymouse
c = Win.GetPixel(mx,my)
h = Win.Hex(word(c,1)) ++ Win.Hex(word(c,2)) ++ Win.Hex(word(c,3))
Win.Debug("rgb value at", mx++",", my, ": #"++c)
Win.Debug("hex value at", mx++",", my, ": #"++c)
- Uses Win.Hex() (Win > Commands by category > Misc), to calculate the hex value of the pixel colour under the mouse & outputs "hex value at x,y: #ffffff"
where
x = x pos of mouse
y = y pos of mouse
#ffffff = a 6 digit hex colour code (#ffffff is actually white)
- Notes
- Use word function to access the individual r, g, or b value, e.g.:
word(Win.GetPixel(100,200), 2)
returns blue (2nd) value at screen position 100, 200.
- Each of the 3 values is between 0 (black) and 255 (white).
- GetPixel1
- Description
- Returns a single number representing the Windows color value of the pixel at screen position x, y where (0,0) is top left.
- Syntax
- Parameters
- Return Value
- a single number representing the Windows value of the color of the pixel at (x,y)
- Examples
- Local mx, my, c, h
mx = xmouse
my = ymouse
c = Win.GetPixel1(mx,my)
h = Win.Hex(c)
Win.Debug("win color value: ", c)
Win.Debug("hex value at", mx++",", my, ": #"++ c)
- Gets the color value of the pixel under the mouse, then uses Win.Hex() to calculate the hex value of the same pixel, outputting both results.
- Notes
- Coordinates
- Left
- Description
- returns left window coordinate of first window matching cl
- Syntax
- Parameters
- Return Value
- distance left edge of window is from left edge of screen
- Examples
- Local winL = Win.Left("*notepad")
- assigns the distance of the left edge of the first notepad window from the left edge of the screen to variable "winT"
- Right
- Description
- returns right window coordinate of first window matching cl
- Syntax
- Parameters
- Return Value
- distance right edge of window is from left edge of screen
- Examples
- Local winR = Win.Right("*notepad")
- assigns the distance of the right edge of the first notepad window from the left edge of the screen to variable "winT"
- Top
- Description
- returns top window coordinate of first window matching cl
- Syntax
- Parameters
- Return Value
- distance top of window is from top of screen
- Examples
- Local winT = Win.Top("*notepad")
- assigns the distance of the top edge of the first notepad window from the top edge of the screen to variable "winT"
- Bottom
- Description
- returns bottom window coordinate of first window matching cl
- Syntax
- Parameters
- Return Value
- distance bottom of window is from top of screen
- Examples
- Local winB = Win.Bottom("*notepad")
- assigns the distance of the bottom edge of the first notepad window from the top edge of the screen to variable "winT"
- Dimensions
- Width
- Description
- Returns the width of the first window matching cl.
- Syntax
- Parameters
- Return Value
- width of the matching window
- Examples
- Win.Debug("width: " ++ Win.Width("under") ++ "px")
- outputs "width: Wpx" to a debug window, where W is the width of the window under the mouse
- Height
- Description
- Returns the height of the first window matching cl.
- Syntax
- Parameters
- Return Value
- height of the matching window
- Examples
- if (Win.Height("*firefox") > 800)
Window.Max("*firefox")
- Checks if the height of the first Firefox window is greater than 600px, & if so, maximises the window.
- Exe
- GetProcessId
- Description
- Returns the process id of the process for the window with handle han.
- Syntax
- Parameters
- Return Value
- Examples
- Win.Debug("process id = " ++ Win.GetProcessId(han))
- GetWorkingDir
- Description
- Retrieves the working directory of the first window matching specified caption list.
- Syntax
- Parameters
- cl
- (cl) caption list to match
- Return Value
- (string) the working directory's full path
- Examples
- Win.Debug(Win.GetWorkingDir("=metapad"))
- ExePath
- Description
- returns full path to exe of first window matching cl
- Syntax
- Parameters
- Examples
- Win.Debug("exe path = " ++ Win.ExePath(han))
- Notes
- Path includes exe filename, e.g.:
Win.Debug(Win.ExePath("*metapad"))
would return the string:
"C:\Program Files\Metapad\metapad.exe"
- ExeName
- Description
- Returns program exe name (without file extension) of the first window matching cl.
- Syntax
- Parameters
- Return Value
- exe name of the program the window(s) in caption list belong to
- Examples
- Local temp = Win.ExeName("Open*")
Win.Debug(temp)
- Assigns variable "temp" the name of the exe the owns the window with caption "Open*". If the program was Notepad, temp would equal "firefox".
- Handle
- ChildHandleList
- Description
- Returns a space-separate list of child window handles for main window matching cl.
- Syntax
- Win.ChildHandleList(cl, text)
- Parameters
- cl
- text
- (string) optional parameter that refines the handle list returned
- Possible Values
- omitted
- Returns all child windows of the first window matching cl.
- "c=classname"
- Only child windows with class "classname" belonging to the first window matching cl are retrieved.
- The "c=" part of the parameter must be included.
- "sometext"
- Only windows with window text matching "sometext" are retrieved.
- "sometext" is any text passed as a single string.
- Return Value
- (string) list of child window handles, separated with spaces.
- Examples
- Win.Debug(win.Childhandlelist("*metapad*"))
- Returns a list of all child window handles that belong to the first Metapad window found.
- Win.Debug(win.Childhandlelist("*metapad*", "c=RichEdit20A"))
- Returns a list of all child window handles with class RichEdit20A that belong to the first Metapad window found.
- Win.Debug(win.Childhandlelist("*metapad*", "quick brown fox"))
- Returns a list of all child window handles containing the text "quick brown fox" that belong to the first Metapad window found.
- Notes
- If using the "text" parameter, *all* the text of the child window must be included for a match.
- GetFocus
- Description
- Returns the handle of the window with focus, which may be a child window.
- Syntax
- Return Value
- Examples
- Local h = Win.GetFocus()
Win.Debug("The window with focus is " ++ Win.Caption(h))
- Puts the handle of window with focus into variable "h", then uses that value to get this window's caption, and outputs that in a debug message.
- Handle
- Description
- Retrieves the handle of the first window matching caption list cl, or the first child window, if window text provided in second parameter.
- Syntax
- Parameters
- cl
- (cl) caption list to match
- txt
- (string) optional, if specified, means the handle of the child window containing text wil be returned
- Return Value
- Examples
- Win.Debug(Win.Handle("*firefox"))
- Outputs the handle currently assigned to Firefox.
- Win.Debug(Win.Handle("*notepad*", "text of my document"))
- Returns handle of child window of notepad that contains "text of my document".
- See Also
- HandleFromPoint
- Description
- Returns the handle of the window at screen position x,y. This may be a child window.
- Syntax
- Parameters
- x
- (integer) x screen coordinate
- y
- (integer) y screen coordinate
- Return Value
- Examples
- Win.Debug(Win.HandleFromPoint(xmouse,ymouse))
- Outputs the handle of the main window under the mouse to a debug window.
- HandleList
- Description
- Returns a space-separated list of window handles matching specified command list.
- Syntax
- Win.HandleList(cl, include_hidden)
- Parameters
- cl
- include_hidden
- (integer) sets whether to include hidden windows
- Accepted Values
- 0
- do not include hidden windows
- 1
- include all hidden windows
- 2
- include hidden windows, except those with blank captions
- Return Value
- (string) list of window handles
- Examples
- Win.Debug(win.HandleList("=firefox", 0))
- Returns a list of visible Firefox windows.
- Win.Debug(win.HandleList("=firefox", 1))
- Returns a list of all Firefox windows.
- Win.Debug(win.HandleList("=firefox", 2))
- Returns a list of all Firefox windows except those without a caption.
- MainHandleFromPoint
- Description
- Returns window handle of main (parent) window at screen position x,y.
- Syntax
- Win.MainHandleFromPoint(x,y)
- Parameters
- x
- (integer) x screen coordinate
- y
- (integer) y screen coordinate
- Return Value
- Examples
- Win.Debug(Win.MainHandleFromPoint(xmouse,ymouse))
- Outputs the handle of the main window under the mouse to a debug window.
- Win.Debug(Win.Caption(Win.MainHandleFromPoint(100,100)))
- Gets the handle of the main window at screen position (100,100), uses that value to determine the window's caption, and outputs the result in a debug window.
- Notes
- If there are a number of windows in that location, the topmost window's main (parent) handle will be returned.
- (0,0) is the top left of the screen.
- Parent
- Description
- Returns the handle of the parent of the window with handle han.
- Syntax
- Parameters
- Return Value
- Examples
- Win.Debug(Win.Parent(Win.HandleFromPoint(xmouse, ymouse)))
- Gets the handle of the parent of the window under the mouse & outputs it to a debug window.
- State
- Enabled
- Description
- Checks whether the first window matching caption list "cl" is enabled.
- Both child and parent windows are looked at to find the first match with cl.
- Syntax
- Parameters
- Return Value
- 1
- first window matching cl is enabled
- 0
- first window matching cl is not enabled
- Examples
- Win.Debug(Win.Enabled("c=ToolbarWindow32"))
- Determines whether the first window with class "ToolbarWindow32" is enabled, and outputs the result to a debug window.
- Exists
- Description
- Checks whether handle "han" is a valid window handle.
- Both child and parent windows are looked at to find the first match with cl.
- Syntax
- Parameters
- Return Value
- 1
- han is a valid window handle
- 0
- han is not a valid window handle
- Examples
- Local h, i
h = Win.Handle("*notepad*")
i = h + 1
Win.Debug(Win.Exists(h))
Win.Debug(Win.Exists(i))
- Stores handle of first notepad window in variable h, then adds 1 to h & stores that in variable i. Debugs whether both numbers are valid window handles.
- FullScreen
- Description
- Checks if foreground window is full screen, or if any window belonging to same process as foreground window is full screen.
- Syntax
- Win.FullScreen()
- Win.FullScreen(allFromProc)
- Parameters
- allFromProc
- Optional
- if specified & set to 1, PowerPro checks all windows belonging to same process as foreground window to see if any are fullscreen
- Return Value
- 1
- 0
- window is not full screen
- Examples
- if (Win.FullScreen())
Win.Debug("the program on top at the moment is full screen")
- if (Win.FullScreen(1))
Win.Debug("the program on top at the moment -- or one of its siblings -- is full screen")
- Notes
- When used with the optional parameter, allFromProc, this function only checks whether any window is fullscreen; it does not return the window handle.
- HasCaption
- Description
- Checks if a window has a caption or toolbar caption.
- Syntax
- Parameters
- han
- window handle
- Optional, default is foreground window.
- Return Value
- 0
- window does not have a caption
- 1
- 2
- window has a toolbar caption
- Examples
- Win.Debug(Win.HasCaption())
- Outputs whether the foreground window has a caption, note parameter han omitted from Win.HasCaption() call.
- Win.Debug(Win.HasCaption("=javaw"))
- Notes
- The first window matching cl is checked, unless no handle is specified, in which case the foreground window is the target.
- Maxable
- Description
- Checks if the first window matching cl has a maximize button.
- Syntax
- Parameters
- Return Value
- 1
- window has a maximize button
- 0
- window does not have a maximize button
- Examples
- if (Win.Maxable("*firefox*"))
Win.Debug("this window can be maximized")
- Maxxed
- Description
- Checks if the first window matching cl is maximized.
- Syntax
- Parameters
- cl
- (string) caption list
- window caption doesn't always work..?
better results using "=exename" or "c=classname" format, or handle
- Return Value
- Examples
- if (Win.Maxxed("*explorer*"))
; do something
- Minable
- Description
- Checks if the first window matching cl has minimize box.
- Syntax
- Parameters
- Return Value
- 1
- window has a minimize box
- 0
- window does not have a minimize box
- Examples
- Local h = "*firefox*"
if (Win.Minable(h))
Win.Minimize(h)
- Minned
- Description
- Checks if first window matching cl is minimized.
- Syntax
- Parameters
- Return Value
- Examples
- if (Win.Minned("*notepad*"))
Win.Maximize("*notepad*")
- Resizable
- Description
- Checks if first window matching cl is resizable.
- Syntax
- Parameters
- Return Value
- Examples
- if (Win.Resizable("*notepad*"))
Bar.Show("WindowTools")
- Checks if notepad is resizable, and if so shows a bar called WindowTools.
- Rolled
- Description
- Checks if first window matching cl is rolled-up.
- Syntax
- Parameters
- Return Value
- Examples
- if (Win.Rolled("*mydoc.txt"))
Win.Move("*mydoc.txt", 10, 10)
- Checks if a file called "mydoc.txt" is rolled up, and if so, moves it to screen position (10,10).
- ToolWindow
- Description
- Checks if first window matching cl is a toolwindow.
- Syntax
- Parameters
- Return Value
- 1
- 0
- window is not a toolwindow
- Examples
- if (Win.ToolWindow(1508310))
; do something
- Notes
- A toolwindow is a PowerPro bar or note.
- Topmost
- Description
- Checks if first window matching cl is topmost.
- Syntax
- Parameters
- Return Value
- Examples
- if (Win.Topmost("*metapad*"))
Win.Keys("foobar")
- TrayMinned
- Description
- Checks if first window matching cl is tray-minned.
- Syntax
- Parameters
- Return Value
- 1
- 0
- window is not tray-minned
- Examples
- if (Win.TrayMinned("*notepad*"))
Win.Show("*notepad*")
- Visible
- Description
- Checks if a window exists, visible or hidden.
- Syntax
- Parameters
- Return Value
- 1
- a window matching cl exists
- 0
- hidden window matching cl exists
- ""
- Examples
- if (Win.Visible("*notepad*"))
Win.Keys("{to *notepad*}magic")
- Text
- GetText(han)
- Description
- Issues a WM_GETTEXT command to the window with handle han; the receiving window may return its text.
- Syntax
- Parameters
- Return Value
- (string) text of the window or child window
- Seems to return window caption, not text within the window..?
- Examples
- Local t = Win.GetText(active)
Win.Debug(t)
- ChildTextByIndex
- Description
- Retrieves the text in the nth childwindow of the first window matching specified caption list.
- Syntax
- Win.ChildTextByIndex(cl, n)
- Parameters
- cl
- (cl) caption list
- PowerPro first looks for visible windows matching cl, then hidden.
- n
- sets variable _EOF_ to:
- 1
- there are less than n child windows
- 0
- Examples
- Win.Debug(Win.ChildTextByIndex("*metapad*, 2))
- Window Area
- Area
- Description
- Determines the area of the window (such as "client", "caption", "max button", etc) at screen position x,y.
- Syntax
- Parameters
- Return Value
- (string) area of the window at that location
- Possible Values
- BORDER
- border of a window that does not have a sizing border
- BOTTOM
- lower horizontal border of the window
- BOTTOMLEFT
- lower-left corner of the window border
- BOTTOMRIGHT
- lower-right corner of the window border
- CAPTION
- CLIENT
- CLOSE
- GROWBOX
- HSCROLL
- LEFT
- left border of the window
- MAXBUTTON
- MENU
- MINBUTTON
- NOWHERE
- on screen background or on a dividing line between windows
- REDUCE
- RIGHT
- right border of the window
- SYSMENU
- control menu or close button in a child window
- TOP
- upper horizontal border of the window
- TOPLEFT
- upper-left corner of the window border
- TOPRIGHT
- upper-right corner of the window border
- TRANSPARENT
- on a window currently covered by another window
- VSCROLL
- Examples
- Win.Debug(win.area(xmouse, ymouse))
- Outputs the area of the window under the mouse.
- Manipulate a Window
- Close
- Description
- Closes first window matching specified caption list.
- Syntax
- Parameters
- cl
- (cl) caption list to match
- Examples
- CloseForce
- Description
- Forces the first window that matches the specified command list to close, & any unsaved information is lost.
- Syntax
- Parameters
- cl
- (cl) caption list to match
- Examples
- Enable
- Description
- Enables or disables the first window matching specified caption list.
- Syntax
- Parameters
- cl
- (cl) caption list to match
- flag
- (boolean) determines if window will be enabled or disabled
- Possible Values
- Examples
- Win.Enable("html help*", 0)
- Disables the first window with caption matching "html help*".
- Win.Enable("html help*", 1)
- Enables the first window with caption matching "html help*".
- Hide
- Description
- hides first visible window matching cl
- Syntax
- Parameters
- cl
- (cl) caption list to match
- Examples
- Maximize
- Description
- Maximizes first visible window matching specified caption list.
- Syntax
- Parameters
- cl
- (cl) caption list to match
- Examples
- Win.Maximize("under")
- Maximizes the window under the mouse.
- Minimize
- Description
- minimizes first visible window matching cl
- Syntax
- Parameters
- cl
- (cl) caption list to match
- Examples
- Win.Minimize("active")
- Minimizes the active window.
- Move
- Description
- Moves the first visible window matching specified caption list to screen position x, y.
- Syntax
- Parameters
- Examples
- Win.Move("=metapad", 100, 100)
- Notes
- Top left of the screen is 0,0.
- OnTop
- Description
- Toggle whether a window is topmost or not.
- Finds first window matching specified caption list, & sets it to topmost if it was not on top, or removes topmost if it was.
- Syntax
- Parameters
- cl
- flag
- (boolean) whether to toggle window topmost state or make it not topmost
- Optional.
- Possible Values
- 1
- 0
- omitted
- toggles the window's topmost state
- Examples
- local cap = "*metapad*"
if (Win.Topmost(cap))
Win.OnTop(cap, 0)
- Checks if a Metapad window is topmost, and if so makes it not topmost.
- ResetFocus
- Description
- If a PowerPro bar or Taskbar icon is the foreground window, gives focus back to the previous foreground window.
- Syntax
- Examples
- Restore
- Description
- Restores the first visible window matching specified caption list.
- Syntax
- Parameters
- Examples
- RollUp
- Description
- Toggles rolled up state of the first window matching specified caption list.
- Syntax
- Parameters
- Examples
- Win.RollUp("*freemind*")
- Rolls up the first Freemind window found, or unrolls it if it is already rolled up.
- SetFocus
- Description
- Sets the focus and foreground to the window or child window with handle han.
- Syntax
- Parameters
- han
- (integer) handle of the window
- Examples
- Win.SetFocus(Win.Handle("xplorer*"))
- Sets the focus to the first window matching caption list "xplorer*", using the Win.Handle function to retrieve the handle of the target window to pass to the Win.SetFocus call.
- SetText
- Description
- Issues a WM_SETTEXT command, which may set the caption text of the window matching specified caption list to supplied text.
- Syntax
- Parameters
- cl
- newtext
- (string) text to set the window caption to
- Examples
- Win.SetText("=metapad", "DOC")
- Show
- Description
- Shows the first window matching specified caption list.
- Syntax
- Parameters
- cl
- how
- (integer) how to show the window
- Optional.
- Possible Values
- 1
- 2
- ignore icon state, just show
- 3
- omitted
- uses PowerPro internal window activation process
- Examples
- if (anywindow("=firefox"))
Win.Show("=firefox")
- Checks if a Firefox window exists, and if so, shows it.
- ShowNA(cl)
- Description
- Shows the first window matching specified caption list without activating it.
- Syntax
- Parameters
- Examples
- Win.ShowNA("*list*")
- Shows the first window matching caption list "*list*" without specifically making it the foreground window.
- Size
- Description
- Resizes the first visible window matching specified caption list to specified size.
- Syntax
- Parameters
- cl
- x
- (integer) width to resize window to
- y
- (integer) height to resize window to
- Examples
- Win.Size("new file*", 450, 300)
- Resizes a window with caption "new file*" to 450x300.
- TrayMin
- Description
- Toggles the "minimized-to-tray" status of the first window matching specified caption list.
- Syntax
- Parameters
- Examples
- Trans
- Description
- Gives the window matching specified caption list the transparency value supplied.
- If supplied value is negative, the window's transparency state is toggled.
- Syntax
- Parameters
- cl
- num
- (integer) transparency value, 0<num<255
- Possible Values
- -num
- toggles windows transparency between num & 0
- 0
- 1-254
- variable transparency level
- 255
- fully transparent; invisible
- Examples
- Win.Trans("new file*", -150)
- Sets window with caption matching "new file*" to transparency 150, unless it already is at that value, in which case it is set to 0.
- TransMouse
- Description
- Finds the first window matching specified caption list and sets its transparency level, also making it so that mouse pass through the window.
- If specified value is negative, reverses transparency state.
- Syntax
- Parameters
- cl
- num
- (integer) transparency value
- Possible Values
- -(num)
- toggles windows transparency between num & 0, and mouse clicks between pass through or not.
- 0
- 1-254
- variable transparency level
- 255
- fully transparent; invisible
- Examples
- Win.TransMouse("=hh",-150)
- Sets the first HTML Help window found to transparency 150 & makes mouse clicks pass through it to the underlying window (or the desktop) -- unless the HTML Help window already has that setting, in which case transparency is set back to 0 & the window is made able to receive mouse clicks again.
- Win.TransMouse("=hh",40)
- Sets the first HTML Help window found to transparency 40 & makes mouse clicks pass through it to the underlying window (or the desktop).
- Windows API Messages
- PostMessage
- Description
- Posts a Windows API message to the the message queue associated with the thread that created the specified window and returns without waiting for the thread to process the message..
- Syntax
- Win.PostMessage(han, msg, wp, lp)
- Parameters
- han
- msg
- wp
- (integer or string) wParam, additional message-specific information
- lp
- (integer or string) lParam, additional message-specific information
- Return Value
- Depends on API message sent.
See Microsoft's MSDN Reference for the Windows API for more information.
- Examples
- Window.PostMessage(0x112,0xF170,2,0xFFFF)
- Turns off the screen until the next mouse or keyboard event.
- Win.PostMessage(Win.Handle("Active"), 273, 28713, 0)
- Changes the active Explorer window to Icon View.
- SendCopyData
- Description
- Sends a WM_COPYDATA message to pass data to the specified window.
- Syntax
- Win.SendCopyData(han, dword, str)
- Parameters
- han
- (integer) target window handle
- dword
- str
- (string) lpdata, pointer to a COPYDATASTRUCT structure that contains the data to be passed
- Return Value
- (boolean)
- True
- receiving application processed the message
- False
- receiving application did not process the message
- is this correct?
- Examples
- See Also
- SendMessage
- Description
- Sends a Windows API message to the window with specified handle, waiting for the message to be processed before returning.
- Syntax
- Win.SendMessage(han, msg, wp, lp)
- Parameters
- han
- msg
- (integer or string) Windows API message
- wp
- (integer) wParam, varies according to msg
- lp
- (integer) lParam, varies according to msg
- Return Value
- Depends on API message sent.
See Microsoft's MSDN Reference for the Windows API for more information.
- Examples
- Window.SendMessage(0x112,0xF170,2,0xFFFF)
- Turns off the screen until the next mouse or keyboard event.
- SendMessageStr
- Description
- Sends a Windows API message to the window with specified handle, lParam is set to point to specified string.
- Syntax
- Win.SendMessageStr(han, msg, wp, str)
- Parameters
- han
- msg
- (integer or string) the Windows API message
- wp
- (integer) wParam, varies according to msg
- str
- (string) lParam is set to point to this
- Return Value
- Examples
- Notes
- This function differs from Win.SendMessage in that Win.SendMessage expects an integer for the 4th parameter.
- is this correct??
- i'm assuming
- Windows API Message Codes QuickRef
- Alpha-order
- WM_A - WM_C
- WM_APP
- WM_ACTIVATE
- WM_ACTIVATEAPP
- WM_AFXFIRST
- WM_AFXLAST
- WM_ASKCBFORMATNAME
- WM_CANCELJOURNAL
- WM_CANCELMODE
- WM_CAPTURECHANGED
- WM_CHANGECBCHAIN
- WM_CHAR
- WM_CHARTOITEM
- WM_CHILDACTIVATE
- WM_CLEAR
- WM_CLOSE
- WM_COMMAND
- WM_COMMNOTIFY (obsolete)
- WM_COMPACTING
- WM_COMPAREITEM
- WM_CONTEXTMENU
- WM_COPY
- WM_COPYDATA
- WM_CREATE
- WM_CTLCOLORBTN
- WM_CTLCOLORDLG
- WM_CTLCOLOREDIT
- WM_CTLCOLORLISTBOX
- WM_CTLCOLORMSGBOX
- WM_CTLCOLORSCROLLBAR
- WM_CTLCOLORSTATIC
- WM_CUT
- WM_D - WM_I
- WM_DEADCHAR
- WM_DELETEITEM
- WM_DESTROY
- WM_DESTROYCLIPBOARD
- WM_DEVICECHANGE
- WM_DEVMODECHANGE
- WM_DISPLAYCHANGE
- WM_DRAWCLIPBOARD
- WM_DRAWITEM
- WM_DROPFILES
- WM_ENABLE
- WM_ENDSESSION
- WM_ENTERIDLE
- WM_ENTERMENULOOP
- WM_ENTERSIZEMOVE
- WM_ERASEBKGND
- WM_EXITMENULOOP
- WM_EXITSIZEMOVE
- WM_FONTCHANGE
- WM_GETDLGCODE
- WM_GETFONT
- WM_GETHOTKEY
- WM_GETICON
- WM_GETMINMAXINFO
- WM_GETTEXT
- WM_GETTEXTLENGTH
- WM_HANDHELDFIRST
- WM_HANDHELDLAST
- WM_HELP
- WM_HOTKEY
- WM_HSCROLL
- WM_HSCROLLCLIPBOARD
- WM_ICONERASEBKGND
- WM_INITDIALOG
- WM_INITMENU
- WM_INITMENUPOPUP
- WM_INPUTLANGCHANGE
- WM_INPUTLANGCHANGEREQUEST
- WM_K - WM_M
- WM_KEYDOWN
- WM_KEYFIRST
- WM_KEYLAST
- WM_KEYUP
- WM_KILLFOCUS
- WM_LBUTTONDOWN
- WM_LBUTTONUP
- WM_LBUTTONDBLCLK
- WM_MBUTTONDOWN
- WM_MBUTTONUP
- WM_MBUTTONDBLCLK
- WM_MDIACTIVATE
- WM_MDICASCADE
- WM_MDICREATE
- WM_MDIDESTROY
- WM_MDIGETACTIVE
- WM_MDIICONARRANGE
- WM_MDIMAXIMIZE
- WM_MDINEXT
- WM_MDIREFRESHMENU
- WM_MDIRESTORE
- WM_MDISETMENU
- WM_MDITILE
- WM_MEASUREITEM
- WM_MENUCHAR
- WM_MENUSELECT
- WM_MOUSEACTIVATE
- WM_MOUSEFIRST
- WM_MOUSEHOVER
- WM_MOUSELAST
- WM_MOUSELEAVE
- WM_MOUSEMOVE
- WM_MOUSEWHEEL
- WM_MOVE
- WM_MOVING
- WM_N - WM_Q
- WM_NCACTIVATE
- WM_NCCALCSIZE
- WM_NCCREATE
- WM_NCDESTROY
- WM_NCHITTEST
- WM_NCLBUTTONDBLCLK
- WM_NCLBUTTONDOWN
- WM_NCLBUTTONUP
- WM_NCMBUTTONDBLCLK
- WM_NCMBUTTONDOWN
- WM_NCMBUTTONUP
- WM_NCMOUSEMOVE
- WM_NCPAINT
- WM_NCRBUTTONDBLCLK
- WM_NCRBUTTONDOWN
- WM_NCRBUTTONUP
- WM_NEXTDLGCTL
- WM_NEXTMENU
- WM_NOTIFY
- WM_NOTIFYFORMAT
- WM_NULL
- WM_PAINT
- WM_PAINTCLIPBOARD
- WM_PAINTICON
- WM_PALETTECHANGED
- WM_PALETTEISCHANGING
- WM_PARENTNOTIFY
- WM_PASTE
- WM_PENWINFIRST
- WM_PENWINLAST
- WM_POWER
- WM_POWERBROADCAST
- WM_PRINT
- WM_PRINTCLIENT
- WM_QUERYDRAGICON
- WM_QUERYENDSESSION
- WM_QUERYNEWPALETTE
- WM_QUERYOPEN
- WM_QUEUESYNC
- WM_QUIT
- WM_NEXTMENU
- WM_R - WM_W
- WM_RBUTTONDBLCLK
- WM_RBUTTONDOWN
- WM_RBUTTONUP
- WM_RENDERALLFORMATS
- WM_RENDERFORMAT
- WM_SETCURSOR
- WM_SETFOCUS
- WM_SETFONT
- WM_SETHOTKEY
- WM_SETICON
- WM_SETREDRAW
- WM_SETTEXT
- WM_SETTINGCHANGE
- WM_SHOWWINDOW
- WM_SIZE
- WM_SIZECLIPBOARD
- WM_SIZING
- WM_SPOOLERSTATUS
- WM_STYLECHANGED
- WM_STYLECHANGING
- WM_SYNCPAINT
- WM_SYSCHAR
- WM_SYSCOLORCHANGE
- WM_SYSCOMMAND
- WM_SYSDEADCHAR
- WM_SYSKEYDOWN
- WM_SYSKEYUP
- WM_TCARD
- WM_TIMECHANGE
- WM_TIMER
- WM_UNDO
- WM_USER
- WM_USERCHANGED
- WM_VKEYTOITEM
- WM_VSCROLL
- WM_VSCROLLCLIPBOARD
- WM_WINDOWPOSCHANGED
- WM_WINDOWPOSCHANGING
- WM_WININICHANGE
- Num-order
- 0x...
- 0-99
- 1
- 2
- 3
- 5
- 6
- 7
- 8
- 10
- 13
- 14
- 15
- 11
- 12
- 16
- 17
- 18
- 19
- 20
- 21
- 22
- 24
- 26
- 26
- 27
- 28
- 29
- 30
- 31
- 32
- 33
- 34
- 35
- 36
- 38
- 39
- 40
- 42
- 43
- 44
- 45
- 46
- 47
- 48
- 49
- 50
- 51
- 55
- 57
- 65
- 68
- 70
- 71
- 72
- 74
- 75
- 78
- 80
- WM_INPUTLANGCHANGEREQUEST
- 81
- 82
- 83
- 84
- 85
- 85
- 100-199
- 123
- 124
- 125
- 126
- 127
- 128
- 129
- 130
- 131
- 132
- 133
- 134
- 135
- 136
- 160
- 161
- 162
- 163
- 164
- 165
- 166
- 167
- 168
- 169
- 200-299
- 256
- 256
- 257
- 258
- 259
- 260
- 261
- 262
- 263
- 264
- 272
- 273
- 274
- 275
- 276
- 277
- 278
- 279
- 287
- 288
- 289
- 300-399
- 400-499
- 500-599
- 512
- 512
- 513
- 514
- 515
- 516
- 517
- 518
- 519
- 520
- 521
- 522
- 522
- 528
- 529
- 530
- 531
- 532
- 533
- 534
- 536
- 537
- 544
- 545
- 546
- 547
- 548
- 549
- 550
- 551
- 552
- 553
- 560
- 561
- 562
- 563
- 564
- 600-699
- 700-799
- 768
- 769
- 770
- 771
- 772
- 773
- 774
- 775
- 776
- 777
- 778
- 779
- 780
- 781
- 782
- 783
- 784
- 785
- 786
- 791
- 792
- 800-899
- 900+
- Notes
- Plugin arguments can take the form of:
- a built-in Function
- plain text in quotes
- a whole number
- another plugin call
- a complex expression
- Most plugins come with a .txt help file, which can be found in PP's plugins folder along with the plugin dll. The help files give more detailed information about the plugins than is found in this Reference.