Tweak Plugin Documentation

Tweak Plugin by Eric Tetz, Copyright 2000.

This document has last been updated on April 19, 2000 (see index below for changes) by Liquid Dust. 

Index

Downloads

General Notes

Conventions:
In all the script code examples below, I use "x" in place of the plugin name. In your app, x is replaced with the name of the plugin object. All script samples are color-coded. The actual functions ("commands") that are included in the plugin, are also color-coded.
Passing string parameters to the plugin
Many of the plugin functions described below use string parameters. To pass a string parameter to a MMB plugin you must call PluginSet() with a string variable. Note, this means you cannot pass a string like this:
    PluginSet("x","This is my string!") 
You must first put the string into a string variable:
    mystring$='This is my string!'
    PluginSet("x","mystring$")
Macro expansion
Every time you pass a string to the plugin, the plugin automatically replaces <SrcDir> and <Embedded> with the correct values. I only support these right now because they seem to be the most important, but if somebody needs some other one, let me know.
back to top

Change Video Modes

This is a set of two functions: 
    VidModeChange
    VidModeRestore
     
You tell the plugin which display mode by passing it a string in the form: 
"WIDTH|HEIGHT|BPP"
Note: BBP (Bits Per Pixel) is optional. 
Change to 640x480 w/ 256 colors
    vidmode$ = '640|480|8'
    PluginSet ("x","vidmode$")
    PluginRun ("x","VidModeChange") 
Restore display mode in effect at app startup:
    PluginRun ("x","VidModeRestore") 
back to top

Open File Dialog

This allows the plugin user to display the display the Windows "Open File" dialog. MMB let's you display this dialog, but it doesn't give a lot of flexibility, and most importantly, it stores the resulting filename in the <File> macro, which cannot be retrieved into a string variable. 

The following functions are included: 

    FDSetDefaultDir - set default directory use by Open File dialog    
    FDSetFilter     - set extension filter used (same as MMB's filter)    
    FDOpenFileDialog    - displays the Open File dialog    
    FDSaveFileDialog    - displays the Save File dialog    
    FDGetFileName   - gets the full path to the file selected by the user    
    FDGetFilePath   - gets just the filename of the file selected by the user    
Example usage: 
    filter$='Foo Documents|*.foo|Bar Documents|*.bar'
    PluginSet ("x","filter$")    
    PluginRun ("x","FDSetFilter");    

    defaultdir$='<SrcDir>\Projects'    
    PluginSet ("x","defaultdir$")    
    PluginRun ("x","FDSetDefaultDir")    

    PluginRun ("x","FDOpenFileDialog");    

    PluginRun ("x","FDGetFilePath")    
    PluginGet ("x","path$")    

    PluginRun ("x","FDGetFileName")    
    PluginGet ("x","filename$");    
back to top

Message Box

This allows the plugin user to display the display the Windows "Message Box" dialog. MMB let's you display this dialog, but it doesn't give you complete control over it. 

Function name:

Message
You specify the message text, title bar text, and flags by calling PluginSet with a specially formatted string: 

"message text|title bar text|flags"

The message text now supports the following characters, which allow for basic text formatting:

     \n    -    New line. All the text that follows after this character, 
                 will be displayed on a new line in the messagebox.
     \t     -    Tab. This inserts a tabspace before the text that follows it.

Note: If you want to insert a literal '\' character, you must preceed it with another slash ('\'), e.g, if you type: 'The directory called C:\\Pictures\\Recent has not been found', it will be displayed like this in the message box: 'The directory called C:\Pictures\Recent has not been found'.

The flags may be combined using the '+' characters. 
 
MsgBox Flags
'b' flags specify which buttons are on the message box box
bo
Ok button (default).
boc
Ok and Cancel buttons.
byn
Yes and No buttons
bync
Yes, No, and Cancel buttons
brc
Retry and Cancel buttons
bari
Abort, Retry, and Ignore buttons
'i' flags control which icon is put on the message box 
ie
An exclamation-point icon appears in the message box. 
ii
An icon consisting of an "i" in a circle appears in the message box.
iq
A question-mark icon appears in the message box.
is
A stop-sign icon appears in the message box.
'd' flags control which buttons is the default 
d1
The first button is the default. Note that the first button is always the default unless 'd1' or 'd2' is specified.
d2
The second button is the default. 
d3
The third button is the default.
'm' flags control the "modality" of the message box 
ma
Application modal (default). The user must respond to the message box before continuing work in the current window. However, the user can move to the windows of other applications and work in those windows.
ms
All applications are suspended until the user responds to the message box. System-modal message boxes are used to notify the user of serious, potentially damaging errors that require immediate attention and should be used sparingly. 
After showng the message box, you can find out which button the user clicked by calling PluginGet() with a string variable 
 
Return Flags
if PluginGet() returns...
user clicked this button....
o
Ok
c
Cancel
y
Yes
n
No
a
Abort 
r
Retry 
i
Ignore 
Example usage: 

** message box with Yes & No buttons and question mark icon
message$='Would you like to register?\n\n\t\Please Do!|My Groovy App|byn+iq'
PluginSet ("x","message$")
PluginRun ("x","Message");

** get the return value and act accordingly 
PluginGet ("x","selected$")
if (selected$ = 'y')
    ** do registration
end 
back to top

Registry IO

This allows you to create, delete, read and write registry keys. 

This is done with a set of five functions:

    RegistrySetRootKey    
    RegistryCreateKey    
    RegistryDeleteKey    
    RegistryGetValue    
    RegistrySetValue    
All the functions require you to first call PluginSet() with a string variable to pass the function it's parameters. After calling any of the functions, calling PluginGet() with an int variable will return 1 if the operation was successful and 0 if it was not. 

Function descriptions:

RegistrySetRootKey

Sets the root key used by all the other registry functions. 

Usage:

Call PluginSet() with one of the following values: 

  • HKEY_CLASSES_ROOT
  • HKEY_CURRENT_CONFIG
  • HKEY_CURRENT_USER
  • HKEY_LOCAL_MACHINE
  • HKEY_USERS
Then call PluginRun("x","RegistrySetRootKey") 

Example: 

    rookey$='HKEY_LOCAL_MACHINE'
    PluginSet("x","rookey$")
    PluginRun("x","RegistrySetRootKey");
Note: The default root key when the plugin DLL is first loaded is HKEY_CURRENT_USER.
RegistryCreateKey
Creates a new key in the registry. Can create more than one key at a time. For example, if you pass were to pass it "Software\\MyMMBApp\\UserSettings", it will create MyMMPApp and UserSettings keys (if they didn't already exist) 

Usage: 

Call PluginSet() with the full path to the key you want to create. The call PluginRun("x","RegistryCreateKey") to create the registry key. 

Example: 

   newkey$='Software\MyAppKey\MySettings'
   PluginSet("x","newkey$")
   PluginRun("x","RegistryCreateKey");
RegistryDeleteKey
Deletes a named key in the registry. Under Windows 95, the key cannot have any subkeys. Under Windows NT, any subkeys will be nuked as well. BE EXTREMELY CAREFUL WITH THIS FUNCTION!!!! I believe that if you were to pass in a zero-length string, or just forget to call PluginSet() first, you could nuke a whole branch of your registry! 

Usage:

Call PluginSet() with the full path to the key you want to delete. The call PluginRun("x","RegistryDeleteKey") with the key you want to delete. 

Example:

   ** delete directory tree one at a time to make sure
   ** it works under Windows 95
   delkey$='Software\MyAppKey\MySettings'
   PluginSet("x","dekkey$")
   PluginRun("x","RegistryDeleteKey");
   delkey$='Software\MyAppKey'
   PluginSet("x","delkkey$")
   PluginRun("x","RegistryDeleteKey");
RegistrySetValue

Set a value for any key in the registry. If the specified value name does not already exists, it will be created. 

Usage:

Call PluginSet() with a string containing the key to set, the name of the value, and the actual value. Each part of the string is separated by the '|' character like this:

   "full path to the registry key|value name|value to set" 

If you want to set the default value for a key, just leave out the value name, like this: 

   "full path to the registry key|value to set"

For example, if you wanted to change the "Control Panel\\Desktop" key in the HKEY_CURRENT_USER branch of the registry. The full MMB script to do that would be: 

    rootkey$='HKEY_CURRENT_USER'    
    PluginSet("x","rootkey$")    
    PluginRun("x","RegistrySetRootKey")    
    
    setvalcmd$='Control Panel\Desktop|wallpaper|C:\Windows\Bubbles.bmp'    
    PluginSet("x","setvalcmd$"    
    PluginRun("x","RegistrySetValue")    
RegistryGetValue

Get a value for any key in the registry. 

Usage:

Call PluginSet() with a string containing the key and value name to read: 

"full path to the registry key|value name" 

If you want to get the default value for a key, just leave out the value name, like this: 

"full path to the registry key" 

For example, here's the full MMB script to read the path of the current Windows wallpaper: 

        rootkey$='HKEY_CURRENT_USER'
        PluginSet("x","rootkey$")
        PluginRun("x","RegistrySetRootKey")

        setvalcmd$='Control Panel\Desktop|wallpaper'
        PluginSet("x","setvalcmd$"
        PluginRun("x","RegistryGetValue")

        PluginGet("x","wallpaper$")
        Message("","wallpaper$")
back to top

Tray Icon

Available tray Functions:
MinimizeToTrayIcon
UpdateTrayIconTooltip
UpdateTrayIcon
TrayIconIsMinimized
Examples:

Minimize the app to the system tray

    icon$ = '<Embedded>\Butterfly.ico'
    PluginSet ("x","icon$")
    PluginRun ("x","MinimizeToTrayIcon")
Setting the tray icon tooltip (only works while minimized)
    tooltip$='My MMB App'
    PluginSet("x","tooltip$")
    PluginRun("x","UpdateTrayIconTooltip")
Update the icon used in the system tray (only works while minimized):
    iconpath$='<Embedded>\MyIcon.ico'
    PluginSet("x","iconpath$")
    PluginRun("x","UpdateTrayIcon")
To find out if the app is minimized (to tray) from script:
    PluginRun("x","TrayIconIsMinimized")
    PluginGet("x","isMinimized")
back to top

Change Shape

You must first create a region data file with CreateRegion.exe. You tell the plugin where the region data is at by calling PluginSet() with the filename. <SrcDir> and <Embedded> macros are supported. You then call PluginRun("PluginName","SetRegion") to apply the region to the MMB app window. 

Available Functions:

SetRegion
ResetRegion
Example of setting the window shape:
    region$ = '<Embedded>\traingle.rgn'
    PluginSet ("x","region$")
    PluginRun ("x","SetRegion")
Note: You can later reset the custom window shape, by using the ResetRegion() function.

Example of  resetting the window shape:

   PluginRun ("x","ResetRegion")

back to top

Get Date & Time

back to top

You pass the plugin a special format string. The plugin replaces the format flags with current date and time information. See the example below. 

Available Date & Time Function:

DateFormat
Format flags:
    %dw = day of the week (0=Sunday,1=Monday,etc)
    %d  = day
    %mo = month
    %y  = year
    %h  = hour
    %m  = minute
    %s  = second
Show the current date & time in a message box
    date$='%d \%mo \%y  %h:%m:%s'
    PluginSet("x","date$")
    PluginRun("x","DateFormat")
    PluginGet("x","date$")
    Message ("","date$")
back to top

Detect App Instances

Allows you to detect how many instances there are of any running application. You must pass the plugin the full path to the app. <Embedded> and <SrcDir> macros are supported. 

Available function:

GetNumInstances
Preventing multiple instances (assumes your exe is named Autorun.exe)
    appPath$='<SrcDir>\Autorun.exe'
    PluginSet("x","appPath$")
    PluginRun("x","GetNumInstances")
    PluginGet("x","instances")
    if (instances > 1)
        Exit()
    end
back to top

Detect CPU Vendor & Speed

Allows you to detect the vendor of the CPU and get a close guess-timate of it's speed. 

Functions: 

    CpuGetName
    CpuGetSpeed
Example:
    PluginRun ("x","CpuGetName")
    PluginGet ("x","cpuName$")
    PluginRun ("x","CpuGetSpeed")
    PluginGet ("x","cpuMhz")

    message$='You have a ' + cpuName$ + ' CPU running at ' + CHAR(cpuMhz) + ' Mhz.'
    Message("","message$")
back to top

Getting Command Line Args

Allows you to get the individual command line arguments used to start up your app. 

Functions: 

    CmdLineCount - get the number of command line arguments
    CmdLineArg   - retrieve an arg
CmdLineCount returns the total number of args.  The args are indexed [1 to NUMARGS].
The first arg is always the path to the app executable.  If you're running in the
designer, or you have compiled the app but did not create a stand-alone app, the
second parameter will be the full path to the .mbd file.
Example:
     PluginRun("x","CmdLineCount")
     PluginGet("x","argc")
     for i = 1 to argc
         PluginSet("x","i")
         PluginRun("x",CmdLineArg")
         PluginGet("x","arg$")
         message$ = 'Arg ' + CHAR(i) + ' is ' + arg$
         Message ("","message$")
     end
back to top

Manipulate INI Files

Allows MMB apps to read and write INI (windows .ini) files.

Available Functions:

IniSetFile         - set the INI file to read and write from
IniRead            - read data from the INI file
IniWrite           - write data to the INI file
IniDelete          - delete a a data item or section from the INI file
NOTE: After calling IniRead, IniWrite and IniDelete you can call PluginGet
with an int variable to determine if the operation was successful.
A return value of 0 means failure, 1 means success.

The INI file format is the standard, familiar Windows INI file format -
section names in square brackets followed by name=value pairs. Like this:

  [SectionName]
  name = Eric Tetz
  occupation = programmer
  sex = uh, yeah
NOTE: INI file reads and writes are cached in memory to make them very fast.
This means that you could do extensive reads, writes and deletes on an INI file
only to open it in notepad and find no changes!  Rest assured that as soon as
your application exits any cached changes will get written to the file.

Function Reference:

IniSetFile

  Set the INI file to read and write from.  You can also use this function to
  create INI files.  If you specify a file that does not exist, the first call
  to IniWrite will create the file.

  Usage:

    Call PluginSet() with the full path to the INI file, then call
    PluginRun("x","IniSetFile").

  Example:

    inifile$ = '<Embedded>\MyApp.INI'
    PluginSet("x","inifile$")
    PluginRun("x","IniSetFile")

IniRead

  Read a value from a section of the INI file

  Usage:

    Call PluginSet() with a string containing the section name and data item name
    formatted like this:

    'section name|data item'

    Then call PluginRun("x","IniRead") to read the data from the INI file and
    PluginGet() to retrieve the data from the plugin.

  Example:

    args$='eric|surname'
    PluginSet("x","args$")
    PluginRun("x","IniRead")
    PluginGet("x","data$")
    Message("data:","data$")

IniWrite

  Write a value to a section of the INI file

  Usage:

    Call PluginSet() with a string containing the section name, data item name, and
    value to write, formatted like this:

    'section name|data item|new value'

    Then call PluginRun("x","IniWrite") to write the value to the INI file.

  Example:

    args$='eric|surname|Tetz'
    PluginSet("x","args$")
    PluginRun("x","IniWrite")

IniDelete

  Delete a data item OR whole section from the INI file.

  Usage: (to delete a single data item)

     Call PluginSet() with a string containing the section name and the data item
     to delete, formatted like this:

     'section name|data item'

     The call PluginRun("x","IniDelete") to delete the data item.

  Example:

     args$='eric|surname'
     PluginSet("x","args$")
     PluginRun("x","IniDelete")

  Usage: (to delete a whole section)

     Call PluginSet() with a string containing the section name to delete.
     The call PluginRun("x","IniDelete") to delete the section and all it's data
     items.

   Example:

     args$='eric'
     PluginSet("x","args$")
     PluginRun("x","IniDelete")

back to top

Popup Menus

Allows MMB apps to display popup menus on a left or right mouse click. It supports one popup menu for any given MMB app, but it (the menu) can change to suit the situation.

Note: Popup menus may not work inside MMB-designer (it sometimes does), but it works fine in the compiled project.

Available Functions:

     MenuReset               - clears all items off the current menu (resets the menu) 
     MenuAddItem          - adds a menu item to the current menu 
     MenuShow               - shows the menu
     MenuSetHandler      - is used for right-mouse click popups
     MenuClearHandler  - resets the current handler (right-click-menu becomes inactive)

Usage of Functions:

MenuReset

This function clears all the current menu items. Call this to destroy all current menus, before creating a new menu.

Example: 

** Get rid of any previously existing menu items
PluginRun("x","MenuReset")
MenuAddItem

This function is used to add items to the popup menu. Use this function repetitively to add as many items as you want to your menu. 

Note: Dividers can also be added by adding a menu item named "-". (See the example below).

Example:

** Create a menu existing out of a couple of items

menuItem$='This is item number ONE'
PluginSet("x","menuItem$")
PluginRun("x","MenuAddItem")

menuItem$='This is item number TWO'
PluginSet("x","menuItem$")
PluginRun("x","MenuAddItem")

menuItem$='This is item number THREE'
PluginSet("x","menuItem$")
PluginRun("x","MenuAddItem")

menuItem$=' This is item number FIVE'
PluginSet("x","menuItem$")
PluginRun("x","MenuAddItem")

** Use the "-" character to add a divider
menuItem$='-'
PluginSet("x","menuItem$")
PluginRun("x","MenuAddItem")

menuItem$='Cancel'
PluginSet("x","menuItem$")
PluginRun("x","MenuAddItem")


MenuShow

Call this function to show the popup menu, after the items have been added. (You can specify a x,y position, or just let it popup at the current mouse position). To get the result of the item that the user has clicked on the menu, call PluginGet("x","selected"). An integer will be returned: 

0 means failure (the user did not click on any menu item); 
– Integers ranging from 1 - the number of menu items. (This indicates the number of the menu item that was clicked. E.g. the third menu item that was declared using MenuAddItem(), will return "3" as an integer (This rule of thumb does not apply to seperators (dividers), since they are not considered actual "menu items" (you cannot click on them or select them)).

Example:

** Show menu and get results
PluginRun("x","MenuShow")
PluginGet("x","selected")

** Process the results
message$='You picked menu item ' + CHAR(selected) + '.'
args$=message$ + '|Results'
PluginSet("x","args$")
PluginRun("x","MsgBox")

If you want to open the popup menu at a specific position, then simply pass the X and Y positions to the plugin.
You should, however, pass in the "x|y" with PluginRun() before calling MenuShow.

Example:

pos$ = '20|20'
PluginSet("x","pos$")
PluginRun("x","MenuShow")
MenuSetHandler

This function is used to make right-click-popup-menus possible, and to run a certain MMB script when a certain menu-item is selected.

Usage:

First create a menu, and then set a handler. The next time the user right-clicks on the MMB window, the menu is shown. After the user selects something on the menu, the handler is called. A "handler" is basically just a keystroke. You should first setup a script to handle "right-click messages". Then specify in MenuSetHandler() what hotkey activates that script. 

You can use any hotkey that is a valid trigger for a MMB script. For example:

"X"
"?"
"CONTROL+LEFT"
"CONTROL+ALT+SHIFT+TAB"
"SHIFT+DELETE"
Example:
** Tell the plugin which keystroke to send to MMB when a menu item is selected...
** This will have the exact same result than if the user physically pressed the keys that 
** triggers a certain script that was set up to react to those keys...
** Now we specify that certain key(s) that triggers a script:

msgHandler$='CONTROL+SHIFT+ALT+A'
PluginSet("x","msgHandler$")
PluginRun("x","MenuSetHandler")

Note: To add a right-click-popup-menu to the tray icon of your minimized app, just call MenuSetHandler() before minimizing, and you can set the handler to something for your tray icon. 

MenuClearHandler

Call this function to clear (reset) the current active handler. By calling this function, the right-click-popup menu will become inactive.

Example:

PluginRun("x","MenuClearHandler")
Understanding and using handlers step by step: (For New Users)
  • Check the option "run script by pressing" in your script object in MMB. (This is the script that will be run when the user selects a right-click-popup-menu item). 
  • Then specify the KeyStrokes that will run the script (e.g. CONTROL + A).
  • Now, set the 'msgHandler$' equal to the keys you have selected.
  • Finally, when the user clicks on a menu item (on the right-click-popup-menu), the keystokes that you specified with the MenuSetHandler() is sent automatically to MMB. This simulates a physical key-press performed by the user. Now, the MMB-Script that is set up to react to (be run on) those specific keystrokes, will be run. 
  • Make sure that all possible integers that can be returned by the popup-menu have been catered for in the script (the script can react differently to every different item selected by the user). Remember that if the integer "0" is returned, it means that the user did not click on the menu, or that no menu item has been selected.
back to top

Enable Client Area Drag

You can use Tweak to enable the "client area drag" and "show window contents while dragging" for the MMB window. "Client area drag" means you can drag the window by clicking anywhere, not just the title bar. "Show window contents while dragging" means your window's graphics are visible while dragging. (Normally Windows shows a drag rectange while dragging and waits until you stop dragging to repaint the window.)

Available Function:

EnableClientAreaDrag
Example:
PluginRun("Tweak","EnableClientAreaDrag")
back to top

Change the Wallpaper

You can use tweak to set the Desktop Wallpaper. You can specify a path to a bitmap image that is to be used as Wallpaper (or maybe use an open-file dialog box, so that the user can choose a bitmap file that he/she prefers (see the TweakDemo)). You can also specify if the change in Wallpaper should be permanent, or temporary (e.g. for previewing). Further more, Tweak aslo provides the ability to specify a particular style in which the Wallpaper should be displayed (centered, tiled or strethed). All of the above is achieved with the following function:
SetWallpaper
To use the function, you have to pass parameters into a string, in the following form:
Bitmap for Wallpaper|Bitmap Display Style|Commit

Bitmap for Wallpaper    - Full path to a Windows bitmap
Bitmap Display Style     - 0=centered, 1=tiled, 2=stretched
Commit (Permanency)   - 0=temporary, 1=permanent (write to the registry)

The "Commit" parameter is optional. If no "commit" value is specified, the Wallpaper will be set permanently (thus, the default for the "commit"-parameter is "1").

Example: (produces tiled permanent "bubbles" as Wallpaper)

*---Set the parameters---*
BitmapPath$='C:\Windows\Bubbles.bmp'
BitmapStyle$='|1'
BitmapPermanent$='|1'
WallpaperStuff$= BitmapPath$ + Bitmapstyle$ + BitmapPermanent$
*---Set the Wallpaper---*
PluginSet("x","WallpaperStuff$")
PluginRun("x","SetWallpaper")
Or, optionally, without the "commit" parameter: (produces the same effect as script above)
*---Set the parameters---*
BitmapPath$='C:\Windows\Bubbles.bmp'
BitmapStyle$='|1'
WallpaperStuff$= BitmapPath$ + Bitmapstyle$
*---Set the Wallpaper---*
PluginSet("x","WallpaperStuff$")
PluginRun("x","SetWallpaper")
back to top

Snap an MMB-application to the Desktop's edges

You can add the ability to snap to the edges of the Windows Desktop, to your MMB-application. If the app window is moved (by the user) within a specified distance (the default is 15 pixels) from the edges of the desktop, it will snap to (align with) the edge(s) of the desktop. 

Available functions

EnableEdgeSnap
DisableEdgeSnap
SetEdgeSnapDistance
GetEdgeSnapDistance
Usage:

EnableEdgeSnap & DisableEdgeSnap

Simply call these functions to enable and disable the "snapping" of the application.

Examples:
 

PluginRun("x","EnableEdgeSnap")
***The default distance is 15 pixels...***

And...

PluginRun("x","DisableEdgeSnap")

SetEdgeSnapDistance

This function is optional. It sets the distance (between the MMB-app and the edge of the Windows Desktop) that will cause the MMB-app to snap to the edge of the desktop. Please note that the value (which is always in pixels) that is passed to the plugin , is passed in the form of an integer, and not in the form of a string.

Example:

***Set the snap distance to 180 pixels***
distance=180
PluginSet("x","distance")
PluginRun("x","SetEdgeSnapDistance")
***Activate snapping...***
PluginRun("x","EnableEdgeSnap")
GetEdgeSnapDistance

This function simply returns the current "snapping distance" in pixels. If no distance was set by using "SetEdgeSnapDistance", it will return the default value of  "15".

Example usage:

PluginRun("x","GetEdgeSnapDistance")
PluginGet("x","result")
result$='If the application is '+ CHAR(result) + ' pixels away from the edge of the Desktop (or closer), it will snap to the edge of the Desktop...'
Message("result$","")
back to top
 
Note that because of a bug in MMB, you cannot run plugin functions in your first page's startup script.