# functions

name: GetFrame
prototype: long GetFrame();
summary: Returns the address of the main MUSHclient frame window
return_value: The memory address of the main frame window.
type_of_object: Method
description:
This returns the memory address of the main MUSHclient MDI frame. This is intended for advanced programmers who wish to access the MUSHclient window in their own programs.

lua_notes:
In Lua the address is given as "light userdata" type. This is not particularly useful in Lua, however you can print it, and you could use it in custom-written programs.


name: ArrayCreate
prototype: long ArrayCreate(BSTR Name);
summary: Creates an array
vb_example: ArrayCreate "spells"
return_value: eBadArrayName: Name cannot be empty eArrayAlreadyExists: Array already exists eOK: Created OK
type_of_object: Method
see_also: ArrayDelete ArrayClear ArrayListAll
doc_name: Arrays
lua_example: ArrayCreate "spells"
description:
This creates an array for use by scripting. The array name may consist of any characters (except the "null" character, hex 00), and is case-sensitive.

The array must be created before it is used.


name: ArrayDelete
prototype: long ArrayDelete(BSTR Name);
summary: Deletes an array
vb_example: ArrayDelete "spells"
return_value: eBadArrayName: Name cannot be empty eArrayDoesNotExist: Array does not exist eOK: Deleted OK
type_of_object: Method
see_also: ArrayCreate ArrayClear ArrayDeleteKey
doc_name: Arrays
lua_example: ArrayDelete "spells"
description:
This deletes a previously-created arrays. All values are discarded. Arrays are automatically deleted when the world is closed, or the plugin closed if the array is in a plugin.


name: ArrayListAll
prototype: VARIANT ArrayListAll();
summary: Gets the list of arrays
description: Returns an array of all the arrays currently defined.
type_of_object: Method
see_also: ArrayListKeys ArrayCreate ArrayDelete ArrayClear
doc_name: Arrays
lua_example: for k, v in pairs (ArrayListAll ()) do Note (v) end
vb_example:
dim arrList

arrList = world.ArrayListAll

If Not IsEmpty (arrList) Then
  
  For Each a In arrList 
    world.note a
  Next

End If

return_value:
If there are no arrays then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the arrays. 

Use "lbound" and "ubound" to find the bounds of the array of arrays (ie. the number of arrays in the list). You can then use "ArrayListKeys" to find the keys for each array.


name: ArrayListKeys
prototype: VARIANT ArrayListKeys(BSTR Name);
summary: Gets the list of all the keys in an array
type_of_object: Method
see_also: ArrayListKeys ArrayGet ArraySet ArrayExport ArrayExportKeys ArrayListValues
doc_name: Arrays
description:
Returns an array of all the keys in the nominated array. You could use this to then examine the value for each key (using ArrayGet).

You can also use ArrayListValues if all you are interested in is the values but not the keys they belong to.

vb_example:
dim keyList

keyList = ArrayListKeys ("spells")

If Not IsEmpty (keyList) Then
  
  For Each k In keyList 
    world.note k & " = " & ArrayGet ("spells", k)
  Next

End If

return_value:
If there are no elements in the nominated array then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the keys in this array. 

Use "lbound" and "ubound" to find the bounds of the array of keys (ie. the number of keys in the list). You can then use "ArrayGet" to find the values for each key.

lua_example:
for k, v in pairs (ArrayListKeys ("spells")) do 
  Note (v) 
end

-- alternative - show keys and values:

table.foreach (ArrayList ("spells"), print)

-- show a particular value:

spells = ArrayList ("spells")
print (spells.dragonskin)

lua_notes:
If the array does not exist, or is empty, Lua returns nil.

There is an extension for Lua only - ArrayList - which returns both keys and values.

See above example. The key of the table is the array key, the value is the array value.


name: ArrayImport
prototype: long ArrayImport(BSTR Name, BSTR Values, BSTR Delimiter);
summary: Imports values into an array from a single string
vb_example: ArrayImport "spells", "dispel magic,15,dragonskin,45,galvanic whip,30", ","
type_of_object: Method
see_also: ArrayListKeys ArrayGet ArraySet ArrayExport ArrayExportKeys
doc_name: Arrays
lua_example: ArrayImport ("spells", "dispel magic,15,dragonskin,45,galvanic whip,30", ",")
description:
Imports key/value pairs into the nominated array.

They keys and values must be separated by the specified delimiter, for example:

dispel magic,15,dragonskin,45,farsight,15,galvanic whip,30

The first word is the key (eg. dispel magic) the second word is the value (eg. 15) and so on, until the list of keys/values is exhausted.

It is an error if the number of keys/values is not even (that is, there should be one value for each key).

The list may be the empty string, in which case nothing is imported.

You may import on top of an existing array (ie. add to it). The new values are slotted in with the existing values. If the new values have the same key as existing values the existing values are overwritten. The return value from this function tells you if this happens.

You specify the delimiter (eg. a comma) so that you can use different delimiters if you want to. If you want to use the delimiter inside the key or value data, then you must precede it (escape it) with a backslash. Also, if you want to have backslashes in the keys or values, use a double-backslash.

return_value:
eBadArrayName: Name cannot be empty
eArrayDoesNotExist: Array does not exist
eArrayNotEvenNumberOfValues: There is not an even number of keys/values
eImportedWithDuplicates: Imported successfully, however there were duplicates which were overwritten
eCannotImport: The data to be imported contains the "escaped delimiter" sequence, and there is no unused character (eg. hex 01) to temporarily convert it to internally for importing purposes.

eOK: Imported OK

lua_notes:
The delimiter is optional, and defaults to the "," character.

As an optional extension you can supply a Lua table as the second argument, 
instead of a delimited string. (In this case there is no third argument).

eg.

t = {
    ['dispel magic'] = 15,
    dragonskin = 45,
    ['galvanic whip'] = 30
    }

ArrayImport ("spells", t)

This effectively lets you import into Lua tables with ArrayImport, and then
export later on with ArrayList.


name: ArrayExport
prototype: VARIANT ArrayExport(BSTR Name, BSTR Delimiter);
summary: Exports values from an array into a single string
vb_example: SetVariable "spells", ArrayExport ("spells", ",")
type_of_object: Method
see_also: ArrayListKeys ArrayGet ArraySet ArrayImport ArrayExportKeys
doc_name: Arrays
lua_example: SetVariable ("spells", ArrayExport ("spells", ","))
lua_notes: The delimiter is optional, and defaults to the "," character.
description:
Exports key/value pairs from the nominated array.

They keys and values will be separated by the specified delimiter, for example:

dispel magic,15,dragonskin,45,farsight,15,galvanic whip,30

The first word is the key (eg. dispel magic) the second word is the value (eg. 15) and so on, until the list of keys/values is exhausted.

The list may be the empty string, which indicates that the array had no values.

You specify the delimiter (eg. a comma) so that you can use different delimiters if you want to. The delimiter must be a single character (eg. ",") other than the backslash character. If the keys, or the values, contain the delimiter they will be "escaped", for example if the delimiter is a comma then any commas will be exported as backslash-comma.  (ie. "," becomes ","). Also, any backslashes are exported as double-backslashes. (eg. "" becomes "").

If you just want the key names and not the values, use ArrayExportKeys.

return_value:
If successful, the return value is a string containing the key/value pairs for the specified array, separated by the delimiter.

If not successful, the return value is a number (type 'long') with one of the following error codes in it:

eBadArrayName: Name cannot be empty
eArrayDoesNotExist: Array does not exist
eBadDelimiter: The delimiter is not a single character, or is the backslash character


name: ArrayGet
prototype: VARIANT ArrayGet(BSTR Name, BSTR Key);
summary: Gets the value of an array item
description: This retrieves the value for a specified key, for a specified array.
vb_example: Note ArrayGet ("spells", "galvanic whip")
type_of_object: Method
doc_name: Arrays
lua_example: Note (ArrayGet ("spells", "galvanic whip"))
lua_notes: Lua returns nil where applicable instead of an "empty variant".
return_value:
The value for the specified key for the specified array.

However if any of the following conditions is met, an "empty" variant is returned:

* Bad array name
* Bad key name
* Array does not exist
* Key does not exist

see_also:
ArrayCreate ArrayClear ArrayDeleteKey ArrayGet ArrayKeyExists ArrayListKeys ArrayGetFirstKey ArrayGetLastKey


name: ArraySet
prototype: long ArraySet(BSTR Name, BSTR Key, BSTR Value);
summary: Sets the value of an array item
description: This sets the value for a specified key, for a specified array.
vb_example: ArraySet "spells", "dragonskin", "45"
type_of_object: Method
see_also: ArrayCreate ArrayClear ArrayDeleteKey ArrayGet ArrayKeyExists ArrayListKeys
doc_name: Arrays
lua_example: ArraySet ("spells", "dragonskin", "45")
return_value:
eBadArrayName: Name cannot be empty
eBadKeyName: Key cannot be empty
eArrayDoesNotExist: Array does not exist
eSetReplacingExistingValue: Value set, however it overwrote an existing value

eOK: Set OK


name: ArrayDeleteKey
prototype: long ArrayDeleteKey(BSTR Name, BSTR Key);
summary: Deletes a key/value pair from an array
vb_example: ArrayDeleteKey "spells", "farsight"
type_of_object: Method
see_also: ArrayCreate ArrayClear ArrayDelete ArraySet ArrayGet
doc_name: Arrays
lua_example: ArrayDeleteKey ("spells", "farsight")
description:
This deletes a key/value pair from an array. You specify which key to delete, and if it exists in the array, it is deleted.

return_value:
eBadArrayName: Name cannot be empty
eBadKeyName: Key cannot be empty
eArrayDoesNotExist: Array does not exist
eKeyDoesNotExist: Key does not exist
eOK: Deleted OK


name: ArrayExists
prototype: boolean ArrayExists(BSTR Name);
summary: Tests to see if the specified array exists
description: This returns TRUE (1) if the specified array exists, and FALSE (0) if it does not.
vb_example: Note ArrayExists ("spells")
type_of_object: Method
see_also: ArrayKeyExists ArrayCreate ArrayDelete ArrayListAll ArrayCount
doc_name: Arrays
lua_example: Note (ArrayExists ("spells"))
return_value:
TRUE if the array exists.
FALSE if it does not exist.

Note: TRUE is a non-zero value, FALSE is the value 0.


name: ArrayKeyExists
prototype: boolean ArrayKeyExists(BSTR Name, BSTR Key);
summary: Tests to see if the specified array key exists
vb_example: Note ArrayKeyExists ("spells", "farsight")
type_of_object: Method
see_also: ArrayKey ArrayCreate ArrayDelete ArrayListAll ArrayCount ArrayListKeys
doc_name: Arrays
lua_example: Note (ArrayKeyExists ("spells", "farsight"))
description:
This returns TRUE (1) if the specified key in the specified array exists, and FALSE (0) if it does not.

return_value:
TRUE if the key in the array exists.
FALSE if it does not exist.

Note: TRUE is a non-zero value, FALSE is the value 0.


name: ArrayCount
prototype: long ArrayCount();
summary: Returns the number of arrays
vb_example: Note "count of arrays = " & ArrayCount
return_value: The number of arrays in the current world, or the current plugin, which may be zero.
type_of_object: Method
see_also: ArraySize ArrayExport ArrayCreate ArrayDelete ArrayListAll
doc_name: Arrays
lua_example: Note ("count of arrays = " .. ArrayCount ())
description:
This returns the number of arrays in the current world (or current plugin, if executed from a plugin).


name: ArrayExportKeys
prototype: VARIANT ArrayExportKeys(BSTR Name, BSTR Delimiter);
summary: Exports keys from an array into a single string
vb_example: Note ArrayExportKeys ("spells", ",")
type_of_object: Method
see_also: ArrayListKeys ArrayGet ArraySet ArrayImport ArrayExport
doc_name: Arrays
lua_example: Note (ArrayExportKeys ("spells", ","))
lua_notes: The delimiter is optional, and defaults to the "," character.
description:
Exports keys from the nominated array.

They keys will be separated by the specified delimiter, for example:

dispel magic,dragonskin,farsight,galvanic whip

The list may be the empty string, which indicates that the array had no values.

You specify the delimiter (eg. a comma) so that you can use different delimiters if you want to. The delimiter must be a single character (eg. ",") other than the backslash character. If the keys contain the delimiter they will be "escaped", for example if the delimiter is a comma then any commas will be exported as backslash-comma.  (ie. "," becomes ","). Also, any backslashes are exported as double-backslashes. (eg. "" becomes "").

If you want the key values as well as the names, use ArrayExport.

return_value:
If successful, the return value is a string containing the keys for the specified array, separated by the delimiter.

If not successful, the return value is a number (type 'long') with one of the following error codes in it:

eBadArrayName: Name cannot be empty
eArrayDoesNotExist: Array does not exist
eBadDelimiter: The delimiter was not a single character, or was the backslash character


name: ArrayGetFirstKey
prototype: VARIANT ArrayGetFirstKey(BSTR Name);
summary: Gets the key of the first element in the array (if any)
vb_example: Note ArrayGetFirstKey ("spells")
type_of_object: Method
doc_name: Arrays
lua_example: Note (ArrayGetFirstKey ("spells"))
lua_notes: Lua returns nil where applicable instead of an "empty variant".
description:
This retrieves the key of the first element in a specified array. You can then use ArrayGet to get the value associated with that key.

The first element is the one with the lowest key, not the one that was inserted first.

You could use this to implement a queue (to pull out the first entry in the queue).

return_value:
The value of the first key for the specified array.

However if any of the following conditions is met, an "empty" variant is returned:

* Bad array name
* Array does not exist
* Array is empty

see_also:
ArrayCreate ArrayClear ArrayDeleteKey ArrayGet ArrayKeyExists ArrayListKeys ArrayGetLastKey ArrayGet


name: ArrayGetLastKey
prototype: VARIANT ArrayGetLastKey(BSTR Name);
summary: Gets the key of the last element in the array (if any)
vb_example: Note ArrayGetLastKey ("spells")
type_of_object: Method
doc_name: Arrays
lua_example: Note (ArrayGetLastKey ("spells"))
lua_notes: Lua returns nil where applicable instead of an "empty variant".
description:
This retrieves the key of the last element in a specified array. You can then use ArrayGet to get the value associated with that key.

You could use this to implement a stack (to pull out the last entry in the stack).

return_value:
The value of the last key for the specified array.

However if any of the following conditions is met, an "empty" variant is returned:

* Bad array name
* Array does not exist
* Array is empty

see_also:
ArrayCreate ArrayClear ArrayDeleteKey ArrayGet ArrayKeyExists ArrayListKeys ArrayGetFirstKey ArrayGet


name: ArrayListValues
prototype: VARIANT ArrayListValues(BSTR Name);
summary: Gets the list of all the values in an array
type_of_object: Method
see_also: ArrayListKeys ArrayGet ArraySet ArrayExport ArrayExportKeys ArrayListKeys
doc_name: Arrays
description:
Returns an array of all the values in the nominated array. That is, the values for each entry but not the keys.

You can also use ArrayListKeys if you want to find the keys instead.

vb_example:
dim valList

valList = ArrayListValues ("spells")

If Not IsEmpty (valList) Then
  
  For Each v In valList 
    world.note v 
  Next

End If

return_value:
If there are no elements in the nominated array then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing all of the values in this array. 

Use "lbound" and "ubound" to find the bounds of the array of values (ie. the number of values in the list).

lua_example:
for k, v in pairs (ArrayListValues ("spells")) do 
  Note (v) 
end

-- alternative - show keys and values:

table.foreach (ArrayList ("spells"), print)

-- show a particular value:

spells = ArrayList ("spells")
print (spells.dragonskin)

lua_notes:
If the array does not exist, or is empty, Lua returns nil.

There is an extension for Lua only - ArrayList - which returns both keys and values.

See above example. The key of the table is the array key, the value is the array value.


name: ResetStatusTime
prototype: void ResetStatusTime();
summary: Resets the time elapsed shown on the status bar
vb_example: world.ResetStatusTime
java_example: world.ResetStatusTime();
perl_example: $world->ResetStatusTime();
return_value: Nothing.
type_of_object: Method
python_example: world.ResetStatusTime
lua_example: ResetStatusTime()
description:
This resets the "connect time" to now, so that the time shown on the status bar counts up from the moment you called this function.


name: ActivateClient
prototype: void ActivateClient();
summary: Activates the main MUSHclient window
vb_example: world.ActivateClient
java_example: world.ActivateClient();
perl_example: $world->ActivateClient;
return_value: Nothing.
type_of_object: Method
see_also: Activate
python_example: world.ActivateClient
lua_example: ActivateClient()
description:
Activates the main MUSHclient window, effectively bringing MUSHclient to the front as the active application.


name: RemoveBacktracks
prototype: BSTR RemoveBacktracks(BSTR Path);
summary: Removes backtracks from a speed walk string
vb_example: world.note world.RemoveBacktracks("4n 2s")
java_example: world.note(world.RemoveBacktracks("4n 2s"));
perl_example: $world->note($world->RemoveBacktracks("4n 2s"));
type_of_object: Method
see_also: EvaluateSpeedwalk ReverseSpeedwalk
python_example: world.note(world.RemoveBacktracks("4n 2s"))
doc_name: speed_walking
lua_example: Note(RemoveBacktracks("4n 2s"))
description:
This takes a speedwalk as an argument and removes any backtracks from it.

For example:  "4n 2s" would be converted to "2n".

A side-effect of this routine is that comments will be removed from speedwalks, and "reverse direction hints" will also be removed. eg. "(open door/close door) {comment}" would be converted to "(open door)".

It will also join directions where possible, eg. "n n n" would become "3n"

return_value:
The supplied string, with the backtracks removed as described above.
If there is an error in the speed walk string then the first character of the returned string will be an asterisk ("*"), and the rest will be an English error message.


name: GetTriggerWildcard
prototype: VARIANT GetTriggerWildcard(BSTR TriggerName, BSTR WildcardName);
summary: Returns the contents of the specified wildcard for the named trigger
type_of_object: Method
see_also: GetTriggerInfo
doc_name: triggers
description:
Once a trigger has matched you can extract any of the wildcards for that trigger using this function.

The wildcards can be specified by name or number (if by number pass a string which is the appropriate number).

You can set up a named wildcard like this:

Match: (?P<who>.*) tells you '(?P<what>.*)'

In this case we have 2 wildcards, named "who" and "what".

Now we can extract wildcards like this:

x = GetTriggerWildcard ("mytrigger", "who")  ' get wildcard named 'who'
x = GetTriggerWildcard ("mytrigger", "what") ' get wildcard named 'what'
x = GetTriggerWildcard ("mytrigger", "22")   ' get wildcard 22 (if it exists)

You can have up to 999 wildcards, plus wildcard 0 which represents the entire matching string.

You can use GetTriggerInfo selector 31 to find how many wildcards matched.

Each wildcard will have a number and may optionally have a name.

vb_example:
dim x

x = GetTriggerWildcard ("mytrigger", "who")  ' get wildcard named 'who'
x = GetTriggerWildcard ("mytrigger", "what") ' get wildcard named 'what'
x = GetTriggerWildcard ("mytrigger", "22")   ' get wildcard 22 (if it exists)

return_value:
The contents of the specified trigger wildcard, as described above.

An EMPTY variant, if the trigger does not exist.

A NULL variant if the trigger name is invalid.

An empty string if the wildcard does not exist. An empty string is the string "", this is different from an EMPTY variant.

lua_example:
local x

x = GetTriggerWildcard ("mytrigger", "who")  -- get wildcard named 'who'
x = GetTriggerWildcard ("mytrigger", "what") -- get wildcard named 'what'
x = GetTriggerWildcard ("mytrigger", "22")   -- get wildcard 22 (if it exists)

lua_notes:
Inside an trigger script function you can access named wildcards by 
simply putting the name after the wildcards argument. eg.

function myTriggerFunction (name, line, wildcards)
  Note (wildcards.who)  --> access named wildcards "who"
end


name: GetAliasWildcard
prototype: VARIANT GetAliasWildcard(BSTR AliasName, BSTR WildcardName);
summary: Returns the contents of the specified wildcard for the named alias
type_of_object: Method
see_also: GetAliasInfo
doc_name: aliases
description:
Once a alias has matched you can extract any of the wildcards for that alias using this function.

The wildcards can be specified by name or number (if by number pass a string which is the appropriate number).

You can set up a named wildcard like this:

Match: Tell (?P<who>.*?) (?P<what>.*)

In this case we have 2 wildcards, named "who" and "what".

Now we can extract wildcards like this:

x = GetAliasWildcard ("myalias", "who")  ' get wildcard named 'who'
x = GetAliasWildcard ("myalias", "what") ' get wildcard named 'what'
x = GetAliasWildcard ("myalias", "22")   ' get wildcard 22 (if it exists)

You can have up to 999 wildcards, plus wildcard 0 which represents the entire matching string.

You can use GetAliasInfo selector 24 to find how many wildcards matched.

Each wildcard will have a number and may optionally have a name.

vb_example:
dim x

x = GetAliasWildcard ("myalias", "who")  ' get wildcard named 'who'
x = GetAliasWildcard ("myalias", "what") ' get wildcard named 'what'
x = GetAliasWildcard ("myalias", "22")   ' get wildcard 22 (if it exists)

return_value:
The contents of the specified alias wildcard, as described above.

An EMPTY variant, if the alias does not exist.

A NULL variant if the alias name is invalid.

An empty string if the wildcard does not exist. An empty string is the string "", this is different from an EMPTY variant.

lua_example:
local x

x = GetAliasWildcard ("myalias", "who")  -- get wildcard named 'who'
x = GetAliasWildcard ("myalias", "what") -- get wildcard named 'what'
x = GetAliasWildcard ("myalias", "22")   -- get wildcard 22 (if it exists)

lua_notes:
Inside an alias script function you can access named wildcards by simply putting the name after the wildcards argument. eg.

function myAliasFunction (name, line, wildcards)
  Note (wildcards.who)  --> access named wildcards "who"
end


name: GetRecentLines
prototype: BSTR GetRecentLines(long Count);
summary: Assembles a block of text from recent MUD output
vb_example: world.Note GetRecentLines (10)
type_of_object: Method
see_also: GetLineInfo
doc_name: info
lua_example: Note (GetRecentLines (10))
description:
This returns a block of text consisting of the nominated number of recently-arrived lines from the MUD.

It excludes notes or commands you type.

It includes lines even if they have been omitted from output by a trigger.

A "line" is a string of text from the MUD followed by a newline character. This is different from the lines returned by GetLineInfo which are physical lines which appear in the output window. Thus a line here might be shown as 5 lines on the screen if they wrapped around to fit them in.

The maximum number of lines stored by MUSHclient is the most recent 100. Thus, even if you request more than 100 lines you will only get 100.

The number you nominate is counted from the bottom, so if you ask for 1 line it will be the most recent, 2 lines will be the most recent 2 lines and so on.

return_value:
A string containing the nominated number of lines of recent MUD output, separated by the newline character (hex 0A).


name: ReloadPlugin
prototype: long ReloadPlugin(BSTR PluginID);
summary: Reloads an installed plugin
vb_example: world.ReloadPlugin "chat" world.ReloadPlugin "753ba7e011f3c8943a885f18"
java_example: world.ReloadPlugin ("chat"); world.ReloadPlugin ("753ba7e011f3c8943a885f18");
perl_example: $world->ReloadPlugin ("chat"); $world->ReloadPlugin ("753ba7e011f3c8943a885f18");
type_of_object: Method
see_also: IsPluginInstalled GetPluginList GetPluginInfo LoadPlugin UnloadPlugin
python_example: world.ReloadPlugin ("chat") world.ReloadPlugin ("753ba7e011f3c8943a885f18")
doc_name: plugins
lua_example: ReloadPlugin ("chat") ReloadPlugin ("753ba7e011f3c8943a885f18")
description:
This is designed to help plugin writers quickly reload a plugin they are testing. You can specify the plugin by unique ID, or by plugin name (assuming the name is unique in your list of plugins).

eg.

world.ReloadPlugin "chat"
world.ReloadPlugin "753ba7e011f3c8943a885f18"

However, a plugin cannot reload itself. That would mean the script was deleted out from under itself. If you try to work around that by having plugin A call plugin B, and plugin B reloads plugin A, you will probably get a crash. If you really want to make a "reload myself" function in a plugin, use something like DoAfterSpecial, to send the "ReloadPlugin" command to the script engine after a 1-second delay.

The intention here is for plugin authors to make an alias that they can type when they want to retest their plugin.

The check for plugin name or plugin ID is not case-sensitive.

return_value:
eNoSuchPlugin: Plugin is not currently installed
eBadParameter: Cannot reload ourselves
ePluginFileNotFound: Plugin file not found
eProblemsLoadingPlugin: Parsing or other problem in plugin file - see error window
eOK: Loaded OK


name: TranslateGerman
prototype: BSTR TranslateGerman(BSTR Text);
summary: Translate German umluat sequences
vb_example: Send TranslateGerman ("ü")
java_example: Send (TranslateGerman ("ü"));
return_value: The supplied text with the sequences described above replaced.
type_of_object: Method
see_also: Replace
doc_name: utils
lua_example: Send (TranslateGerman ("ü"))
description:
This function translates various German sequences to the non-umluat versions for MUDs that do not support umluats, as follows:

 ü to ue
 Ü to Ue
 ä to ae
 Ä to Ae
 ö to oe
 Ö to Oe
 ß to ss


name: Accelerator
prototype: long Accelerator(BSTR Key, BSTR Send);
summary: Add or modify an accelerator key (keystroke to command mapping)
return_value: eBadParameter - the keystroke combination was not accepted eOK - added OK
type_of_object: Method
see_also: AcceleratorList AcceleratorTo
doc_name: macros
description:
This lets you add or amend the behaviour of MUSHclient "accelerator" keys. For example, you could make Ctrl+E become "eat meat".

These changes only apply to the current world (the one the script function is run in). They override any existing macros or accelerator keys defined for MUSHclient's default behaviour.

You specify two arguments, the keystroke to add or amend, and the text to be sent. The text is sent to the MUSHclient command processor, and can thus contain aliases, speedwalks, script commands, or anything you might normally type into the command window. 

For example, to execute a script simply prefix the script command with the scripting prefix. Or alternatively, make up a word you wouldn't normally type (like "SFDSHHG$%(&") and make an alias to match that. Then in the alias do whatever you want to do.

See also AcceleratorTo which lets you specify where to send the command (eg. script, speedwalk).

The keystroke consists of this syntax:

CTRL + ALT + SHIFT + key

The modifiers CTRL, ALT and SHIFT are all optional, and are not case-sensitive. They can appear in any order. 

The key can be one of the following:

0 1 2 3 4 5 6 7 8 9
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Accept Add Apps Attn Backspace Cancel Capital Clear Control Convert Crsel Decimal Delete Divide Down End Enter Ereof Esc Execute Exsel F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 F16 F17 F18 F19 F20 F21 F22 F23 F24 Final Hangeul Hangul Hanja Help Home Insert Junja Kana Kanji LButton LControl LMenu LShift LWin Left MButton Menu ModeChange Multiply NonConvert Noname Numlock Numpad0 Numpad1 Numpad2 Numpad3 Numpad4 Numpad5 Numpad6 Numpad7 Numpad8 Numpad9 Oem_clear Pa1 PageDown PageUp Pause Play Print ProcessKey RButton RControl RMenu RShift RWin Right Scroll Select Separator Snapshot Space Subtract Tab Up Zoom

They are not all guaranteed to work in the way you might expect. These names were obtained from the Windows include files. Some keys may be trapped by the operating system, or not be available on your PC.

Reasonable values to use would be things like:

Alt+Down
Shift+Ctrl+F2
Ctrl+N
PageUp
Ctrl+PageUp
F5
Ctrl+Shift+F9

--------

To disable a previously-assigned accelerator, call this function with an empty string as the command. eg

Accelerator "Ctrl+K", ""  ' return to default behaviour

If you wanted to make a key simply "do nothing" then you will need to do something like send an empty script, or make a "do nothing" alias, and call that. eg.

Accelerator "Ctrl+K", "/"  ' execute empty script
Accelerator "Ctrl+K", "DO_NOTHING_ALIAS"  ' call an alias that does nothing

The "do nothing" alias might be the safer approach, in case someone has changed the scripting prefix to something other than "/".


----------

To see the name for a particular keypress use the Input menu -> Key Name dialog. This lets you type a key and have its name displayed. This name can then be used in this function.

vb_example:
Accelerator "Ctrl+K", "kill"
Accelerator "Ctrl+F", "follow"
Accelerator "Ctrl+E", "eat meat"
Accelerator "Alt+F2", "/Note ""oops"""

java_example:
Accelerator ("Ctrl+K", "kill")
Accelerator ("Ctrl+F", "follow")
Accelerator ("Ctrl+E", "eat meat")
Accelerator ("Alt+F2", "#4s 3e")  // speedwalk

perl_example:
$world->Accelerator ("Ctrl+K", "kill")
$world->Accelerator ("Ctrl+F", "follow")
$world->Accelerator ("Ctrl+E", "eat meat")
$world->Accelerator ("Alt+F2", "#4s 3e")  # speedwalk

lua_example:
Accelerator ("Ctrl+K", "kill")
Accelerator ("Ctrl+F", "follow")
Accelerator ("Ctrl+E", "eat meat")

-- execute a script
Accelerator ("Ctrl+M", "/DoCommand 'preferences'")

Accelerator ("Ctrl+E", "") -- revert to original behaviour for Ctrl+E


name: MapColour
prototype: void MapColour(long Original, long Replacement);
summary: Changes the colour mapping - the way colours are displayed
vb_example: MapColour ColourNameToRGB ("red"), ColourNameToRGB ("green")
java_example: MapColour (ColourNameToRGB ("red"), ColourNameToRGB ("green"))
return_value: None.
type_of_object: Method
see_also: ColourNameToRGB RGBColourToName GetMapColour MapColourList Redraw
doc_name: colours
lua_example: MapColour (ColourNameToRGB ("red"), ColourNameToRGB ("green"))
description:
You can specify a "map" of an original colour to the colour you want displayed.

The intention here is to let you override the colours sent down by MUDs, particularly using MXP colours, which are not subject to the normal ANSI colour palette.

For example, if a MUD annoys you by using a lot of red letters, you could do this:

MapColour (ColourNameToRGB ("red"), ColourNameToRGB ("green"))

The mapping is done at the last moment, in the output window display routine. The rest of MUSHclient will continue normally as if the colours had not changed.

You can map any number of colours, within reason. Potentially there are 16,777,216 different colours (2 to the power 24) however in practice a particular MUD is likely to only use a handful.

The colour must match *exactly* or the translation will not occur.

The arguments to the function are RGB colours (that is, numbers in the range 0 to 16,777,215) however you can use the function ColourNameToRGB as shown above if you want to use colour names.

The colour number is really made up of three bytes:

Red (low-order byte), ie. 0 to 255
Green (middle byte), ie. 0 to 255 multiplied by 256
Blue (higher-order byte), ie. 0 to 255 multiplied by 65536

To find the colour of a particular piece of text in the output window (so you can know the "from" colour) you can select it (eg. double-click) and then use the Display menu -> Text Attributes.

This will show you the Text and Background RGB colours (in HTML format). You can use those colours in the function ColourNameToRGB to translate them to numbers. eg.

x = ColourNameToRGB ("#FF00FF")

You can find the current mapping of a colour with GetMapColour, and a list of all mapped colours with MapColourList.

To make the new colours take effect immediately, call Redraw. This would only be necessary if you are changing colours "on the fly". If you are just customising colours at world startup this would not be necessary.


name: AcceleratorList
prototype: VARIANT AcceleratorList();
summary: List defined accelerators
type_of_object: Method
see_also: Accelerator AcceleratorTo
doc_name: macros
description:
Returns an array of all the accelerator keys currently defined, in the format:

keystroke = text<tab>[sendto]

eg.

Ctrl+E = eat meat<tab>[0]
Ctrl+F = follow
Ctrl+K = 4s 3e<tab>[11]
Ctrl+B = DoAfter(5, "sigh")<tab>[12]

If the "send to" field is "send to execute" (which is 10) then it is omitted (as in the "follow" example above), for backwards compatibility with versions of MUSHclient prior to 4.27. 

Version 4.27 implemented the AcceleratorTo function, which lets you specify where the accelerator text is sent to.

If "send to" field is not 10 then the "send to" field number is specified as a number in square brackets at the end of the text, preceded by the tab character (hex 0x09).

The "SendTo" argument specifies where the text is to be sent to when you press the accelerator key. It can be one of:

0: World 
1: Command window
2: Output window
3: Status line
4: Notepad (new)
5: Notepad (append)
6: Log File 
7: Notepad (replace)
8: Command queue
9: Send To Variable
10: Execute (re-parse as command)
11: Speedwalk (send text is speedwalk, queue it)
12: Script (send to script engine)
13: Immediate (send to world in front of speedwalk queue)
14: Script - after omit (send to script engine, after lines have been omitted)

vb_example:
dim accList

arrList = world.AcceleratorList

If Not IsEmpty (accList) Then
  
  For Each a In arrList 
    world.note a
  Next

End If

return_value:
If there are no accelerators defined then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the keystrokes and contents of each accelerator. 

Use "lbound" and "ubound" to find the bounds of the array of list (ie. the number of accelerators in the list).

lua_example:
-- simple example

for _, v in pairs (AcceleratorList ()) do 
  Note (v) 
end

-- complex example - filters on a supplied string

function FindCommand (what)
  -- search all accelerators for wanted string
  for _, v in pairs (AcceleratorList ()) do
    if string.find (string.upper (v), string.upper (what), 1, true) then
      print (v)
    end	-- if
  end  -- for
end   -- function

FindCommand "eat"


-- example of extracting out the keystroke, what is sent, and where it is sent:


accels = AcceleratorList ()

if accels then
  
  for _, v in ipairs (accels) do

    local keystroke, what, where = string.match (v, "^(%S+) = (.*)%[(%d-)%]$")
    if where then
       where = tonumber (where)
    else
       keystroke, what = string.match (v, "^(%S+) = (.*)$")
       where = sendto.execute
    end -- if

    print ("keystroke =", keystroke)
    print ("what =", what)
    print ("where =", where)

  end -- for

end -- if


-- another example that turns the result into an easier-to-use table:


local accels = AcceleratorList ()
local taccels = {}

if accels then
  
  for _, v in ipairs (accels) do

    local keystroke, what, where = string.match (v, "^(%S+) = (.*)%[(%d-)%]$")
    if where then
       where = tonumber (where)
    else
       keystroke, what = string.match (v, "^(%S+) = (.*)$")
       where = sendto.execute
    end -- if

    taccels [keystroke] = { send = what, where = where }

  end -- for

end -- if

tprint (taccels)

lua_notes:
The example above shows how you might search for accelerators matching a particular string.

The latter examples shows extracting out the original keystroke, send text, and where it is sent.

Note that the accelerator list is numerically keyed, not keyed by the keystroke.


name: GetMapColour
prototype: long GetMapColour(long Which);
summary: Returns the mapping for how a particular colour will be displayed
description: Returns the RGB code for how a particular colour is going to be displayed.
vb_example: colour = MapColour (ColourNameToRGB ("red"))
java_example: colour = MapColour (ColourNameToRGB ("red"))
type_of_object: Method
see_also: ColourNameToRGB RGBColourToName GetMap MapColourList
doc_name: colours
lua_example: colour = MapColour (ColourNameToRGB ("red"))
return_value:
The RGB code corresponding to the colour in the colour mapping table. If the colour is not present, the supplied argument will be returned.


name: MapColourList
prototype: VARIANT MapColourList();
summary: Returns an array of all the mapped colours
type_of_object: Method
see_also: ColourNameToRGB RGBColourToName GetMapColour MapColou
doc_name: colours
description:
Returns a variant array of all the colours that have been mapped for this world. eg.

black = red
blue = gold

vb_example:
dim mapList

mapList= world.MapColourList

If Not IsEmpty (mapList) Then
  
  For Each v In mapList
    world.note v 
  Next

End If

return_value:
If there are no colours mapped then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the source and destination colours with an " = " symbol between them. 

However for Lua, it returns a table where the key is the original colour and the value is the replacement colour.

Use "lbound" and "ubound" to find the bounds of the array of variables (ie. the number of colours in the list).

lua_example:
-- show all colours and their values (RGB values)

for k, v in pairs (MapColourList()) do 
  Note (k, " = ", v) 
end

lua_notes:
Under Lua this function returns a table of all mapped colours and their values, 
keyed by the RGB colour code.

Thus you can directly access colours from the table, like this:

-- show value for colour 255...

print (MapColourList() [255])

Note that since this will return only colours in the table, if the colour doesn't exist in the mapping table, you will get nil from this example.


name: SpellCheck
prototype: VARIANT SpellCheck(BSTR Text);
summary: Spell checks an arbitrary string of text
type_of_object: Method
see_also: SpellCheckCommand AddSpellCheckWord SpellCheckDlg
doc_name: spellcheck
description:
This function lets you call the MUSHclient spell-checker from a script on any arbitrary text string.

Note that if the spell-check engine has not been initialised (eg. the DLL is not present, or the spell check dictionary is not there), it returns the Empty variant (or nil in Lua).

You supply a string of text to be checked. 

If there are no spelling errors, the number zero is returned.

If there are spelling errors, a variant array of all of the misspelt words is returned. You can then iterate through that array to display the misspelt words.

If your spell checker has been configured to detect duplicates (eg. "a bird in the the hand") then they will be returned as duplicated words in the list (eg. "the the"). You could detect that by looking for a space in the returned word.

The spell checking is done with the currently-configured spell-check options (eg. whether words in capitals are checked, whether duplicates are checked).

There is no GUI interface (that is, no "correct this word") dialog box will appear.

vb_example:
result = SpellCheck _
  ("Twas brillig, and the slithy toves Did gyre and gimble in the the wabe")

Note vartype (result) ' array of variants will be 8204

if vartype (result) = (vbArray + vbVariant) then
  For Each w In result
      world.note w
    Next
elseif IsEmpty (result) then
  Note "Spell check not available"
else
  Note "No spelling errors"
end if

return_value:
If the spell checker is not available an Empty variant (or nil in Lua).

If there were no spelling errors, a numeric result of zero.

If there were spelling errors, a variant array consisting of each misspelt word. If the same word was misspelt twice, it is only returned once. The array of misspelt words is in alphabetic order.

lua_example:
result = SpellCheck (
  "Twas brillig, and the slithy toves Did gyre and gimble in the the wabe")

print (type (result))

if result == nil then
  Note "Spell check not available"
elseif result == 0 then
  Note "No spelling errors"
else
 for _, v in pairs (result) do print (v) end
end


name: MakeRegularExpression
prototype: BSTR MakeRegularExpression(BSTR Text);
summary: Converts wildcard matching text to a regular expression
vb_example: Note MakeRegularExpression ("* goes *")
java_example: Note (MakeRegularExpression ("* goes *"))
return_value: The original string converted to a regular expression.
type_of_object: Method
lua_example: Note (MakeRegularExpression ("* goes *"))
description:
This function provides an interface to the internal routine that MUSHclient uses to convert trigger and alias "simple" wildcard expressions to full regular expressions. It is exactly the same result as provided by clicking on the "Convert to regular expression" button in the Edit Trigger dialog.

Example:

print (MakeRegularExpression ("* goes *"))

Output:

^(.*?) goes (.*?)$

The behaviour is basically:

* Put ^ at the start of the expression

* Put $ at the end of the expression

* Convert each occurrence of "*" to "(.*?)"

* Non-printable characters in the range 0x01 to 0x1F become hex sequences

* Non alphanumeric characters are escaped with a backslash.


name: SpellCheckCommand
prototype: long SpellCheckCommand(long StartCol, long EndCol);
summary: Spell checks the text in the command window
vb_example: result = SpellCheckCommand (5, 20) if result = 0 then Note "spelling error detected" end if
type_of_object: Method
see_also: SpellCheck AddSpellCheckWord
doc_name: spellcheck
description:
This function lets you call the MUSHclient spell-checker from a script to check the command window.

The intention here is to let you filter out commands that would naturally fail the spell check, and only check ones you want. eg. "say xxx"

You can specify a start and end column (these are 1-relative, that is the first column is column 1). You can use these to remove special words that might be at the start of the command.

eg.

SetRoomDesc "this is my description"

In this case you might make an plugin that matches on:

SetRoomDesc "*"

Inside the plugin you could work out the start and end column for the "real" text and specify that for the spell checker.

If the start column or the end column is less than 1, or the end column is not greater than the start column, then the entire command window will be checked.

eg. to check the entire command window:  SpellCheckCommand (0, 0)

The function returns:

-1 : spell check engine not initialised successfully

0 : spell check cancelled

1 : spell check completed OK

The spell checking is done with the currently-configured spell-check options (eg. whether words in capitals are checked, whether duplicates are checked).

If there is a spelling error in the selected text, a GUI window will pop-up requesting corrective action.

The the Lua example below for a suggested way of conditionally spellchecking certain commands. Make a plugin, and in that plugin put the function OnPluginCommand. This is called every time you send a command to the MUD.

In the script below it does a regular expression check to find what command you have entered. In the example if you "say" or "tell" something, then the "something" part (the captured pattern) is sent to SpellCheckCommand with the start and end column being those from the regular expression capture.

If the check fails, it returns false to stop sending the command.

If the check succeeds, it gets the command text from the command window, in case the spell check changed it.

If it changed, it returns false to stop *this* command being sent, and does a "Send" of the modified one.

If it didn't change (ie. no spelling errors at all, or the errors were ignored) then the original command is allowed to proceed.

return_value:
-1 : spell check engine not initialised successfully

0 : spell check cancelled (cancel button pressed)

1 : spell check completed OK (possibly after amending the text in the window)

lua_example:
function OnPluginCommand (sText)

  a, b, c = rex.new ("(?:say|tell) (.+)"):exec (sText)

  if a == nil then
    return true  -- not matched our regular expression
  end	-- if

  -- matched regular expression - check the command
  check = SpellCheckCommand (c [1], c [2])

  -- if check failed, cancel sending
  if check == 0 then
    return false	-- cancelled, don't process
  end

  -- if command hasn't changed, allow it to go
  if GetCommand () == sText then
    return true
  end

  -- get the amended command, send that instead
  Send (GetCommand ())
  return false

end


name: MoveMainWindow
prototype: void MoveMainWindow(long Left, long Top, long Width, long Height);
summary: Move and resize the main MUSHclient window
vb_example: MoveMainWindow 1, 1, 640, 480
java_example: MoveMainWindow (1, 1, 640, 480)
return_value: None.
type_of_object: Method
doc_name: utils
lua_example: MoveMainWindow (1, 1, 640, 480)
description:
This function moves and resizes the main MUSHclient window (the frame window inside which all world windows reside).

Specify the left and top co-ordinates in pixels.

Specify the width and height of the window in pixels.

Note that if you move the window off the screen (eg. to -1000, -1000) it will become invisible.

No checking is performed on the arguments to this function.

see_also:
MoveWorldWindow MoveNotepadWindow GetMainWindowPosition GetWorldWindowPosition GetNotepadWindowPosition SetCommandWindowHeight SetToolBarPosition


name: MoveWorldWindow
prototype: void MoveWorldWindow(long Left, long Top, long Width, long Height);
summary: Move and resize a world window
vb_example: MoveWorldWindow 1, 1, 640, 480
java_example: MoveWorldWindow (1, 1, 640, 480)
return_value: None.
type_of_object: Method
doc_name: utils
lua_example: MoveWorldWindow (1, 1, 640, 480, 2) -- move 2nd window
description:
This function moves and resizes the current world's window.

Specify the left and top co-ordinates in pixels.

Specify the width and height of the window in pixels.

Note that if you move the window off the screen (eg. to -1000, -1000) it will become invisible.

No checking is performed on the arguments to this function.

The co-ordinates are relative to the client area of the main MUSHclient window.

In other words, position 1, 1 is the very top-left corner of the MUSHclient frame window.

To specify a window other than the first window either use Lua (see below) or the function MoveWorldWindowX.

see_also:
MoveMainWindow MoveNotepadWindow GetMainWindowPosition GetWorldWindowPosition GetNotepadWindowPosition MoveWorldWindowX SetWorldWindowStatus SetCommandWindowHeight SetToolBarPosition

lua_notes:
Lua has an optional 5th argument which is the window number to move. The first (main) window is window 1.

If you do Window -> New Window then you will get more windows, these will be 2, 3, 4 and so on.

You can use GetInfo (235) to find how many windows are currently open.


name: MoveNotepadWindow
prototype: long MoveNotepadWindow(BSTR Title, long Left, long Top, long Width, long Height);
summary: Move and resize the specified notepad window
vb_example: MoveNotepadWindow "my_notepad", 1, 1, 640, 480
java_example: MoveNotepadWindow ("my_notepad", 1, 1, 640, 480)
return_value: 0: Could not do it (notepad window not found) 1: Moved OK
type_of_object: Method
doc_name: notepad
lua_example: MoveNotepadWindow ("my_notepad", 1, 1, 640, 480))
description:
This function moves and resizes the specified notepad's window.

Specify the left and top co-ordinates in pixels.

Specify the width and height of the window in pixels.

Note that if you move the window off the screen (eg. to -1000, -1000) it will become invisible.

No checking is performed on the arguments to this function.

The co-ordinates are relative to the client area of the main MUSHclient window.

In other words, position 1, 1 is the very top-left corner of the MUSHclient frame window.

If the notepad window cannot be found, the function returns false (zero).

see_also:
MoveMainWindow MoveWorldWindow GetMainWindowPosition GetWorldWindowPosition GetNotepadWindowPosition NotepadFont NotepadColour GetNotepadList SetToolBarPosition


name: GetSysColor
prototype: long GetSysColor(long Index);
summary: Gets the colour of various windows items
vb_example: Note RGBColourToName (GetSysColor (4)) ' --> may print "silver"
java_example: Note (RGBColourToName (GetSysColor (4)))
type_of_object: Method
see_also: GetSystemMetrics RGBColourToName
doc_name: info
lua_example: Note (RGBColourToName (GetSysColor (4))) --> silver
description:
This function directly calls GetSysColor in Windows. It returns the colour used by various items as currently configured in Windows, based on the selector (Index), as follows:

Scrollbar = 0
Background = 1
Active caption = 2
Inactive caption = 3
Menu = 4
Window = 5
Window frame = 6
Menu text = 7
Window text = 8
Caption text = 9
Active border = 10
Inactive border = 11
Application workspace = 12
Highlight = 13
Highlight text = 14
Button face = 15
Button shadow = 16
Gray text = 17
Button text = 18
Inactive caption text = 19
Button highlight = 20
3D dark shadow = 21
3D light = 22
Info text = 23
Info bk = 24

return_value:
The RGB code corresponding to the selected colour index.

If the index is out of range, zero is returned.


name: GetSystemMetrics
prototype: long GetSystemMetrics(long Index);
summary: Returns selected system information from Windows
vb_example: Note GetSystemMetrics (0) ' --> 1024 Note GetSystemMetrics (1) ' --> 768
java_example: Note (GetSystemMetrics (0)) // --> 1024 Note (GetSystemMetrics (1)) // --> 768
return_value: A number corresponding to the selected metric. If the number is out of range, zero is returned.
type_of_object: Method
see_also: GetSysColor
doc_name: info
lua_example: Note (GetSystemMetrics (0)) --> 1024 Note (GetSystemMetrics (1)) --> 768
description:
The GetSystemMetrics function retrieves various system metrics (widths and heights of display elements) and system configuration settings. All dimensions retrieved by GetSystemMetrics are in pixels. 

The information returned depends on the selector (Index), as follows:

CX screen = 0
CY screen = 1
CX vscroll = 2
CY hscroll = 3
CY caption = 4
CX border = 5
CY border = 6
CX dialog frame = 7
CY dialog frame = 8
CY v thumb = 9
CX h thumb = 10
CX icon = 11
CY icon = 12
CX cursor = 13
CY cursor = 14
CY menu = 15
CX full screen = 16
CY full screen = 17
CY kanji window = 18
Mouse present = 19
CY vscroll = 20
CX hscroll = 21
Debug = 22
Swap button = 23
Reserved1 = 24
Reserved2 = 25
Reserved3 = 26
Reserved4 = 27
CX min = 28
CY min = 29
CX size = 30
CY size = 31
CX frame = 32
CY frame = 33
CX min track = 34
CY min track = 35
CX double click = 36
CY double click = 37
CX icon spacing = 38
CY icon spacing = 39
Menu drop alignment = 40
Pen windows = 41
DBCS enabled = 42
Cmouse buttons = 43
Secure = 44
CX edge = 45
CY edge = 46
CX minspacing = 47
CY minspacing = 48
CX smicon = 49
CY smicon = 50
CY smcaption = 51
CX smsize = 52
CY smsize = 53
CX menusize = 54
CY menusize = 55
Arrange = 56
CX minimized = 57
CY minimized = 58
CX maxtrack = 59
CY maxtrack = 60
CX maximized = 61
CY maximized = 62
Network = 63
Clean boot = 67
CX drag = 68
CY drag = 69
Show sounds = 70
CX menucheck = 71 
CY menucheck = 72
Slow machine = 73
Mid-east enabled = 74
Mouse wheel present = 75
X virtual screen = 76
Y virtual screen = 77
CX virtual screen = 78
CY virtual screen = 79
C monitors = 80
Same display format = 81


name: GetMainWindowPosition
prototype: BSTR GetMainWindowPosition();
summary: Returns the position and size of the main MUSHclient window
vb_example: Note GetMainWindowPosition
java_example: Note (GetMainWindowPosition ())
type_of_object: Method
see_also: MoveWorldWindow MoveNotepadWindow MoveMainWindow GetNotepadWindowPosition GetWorldWindowPosition
doc_name: info
lua_example: table.foreach (GetMainWindowPosition (), print)
description:
This function returns the size of the main MUSHclient window (the frame window inside which all world windows reside), in pixels.

For normal scripting languages these return a string, like this: "89,18,825,654". For Lua, see below.

return_value:
Returns a string in the form:

left,top,width,height

eg. "89,18,825,654"

For Lua, returns a table containing:

top=(value)
height=(value)
left=(value)
width=(value)

lua_notes:
In Lua it returns a table with four entries, like this:

top=18
height=654
left=89
width=825

In Lua you can supply an optional boolean argument. If true, a different method of calculating the window position is used (calling GetWindowRect rather than GetWindowPlacement). This method gives a more accurate result if you use "Aero Snap" under Windows 7 or higher. However it may return inaccurate results if the window is minimized.

eg.

GetMainWindowPosition (true)

The default is false, the original behaviour.


name: GetWorldWindowPosition
prototype: BSTR GetWorldWindowPosition();
summary: Returns the position and size of the current world window
vb_example: Note GetWorldWindowPosition
java_example: Note (GetWorldWindowPosition ())
type_of_object: Method
doc_name: info
lua_example: table.foreach (GetWorldWindowPosition(), print)
description:
This function returns the size of the current world's window, in pixels.

For normal scripting languages these return a string, like this: "0,0,669,479". For Lua, see below.


To specify a window other than the first window either use Lua (see below) or the function GetWorldWindowPositionX.

return_value:
Returns a string in the form:

left,top,width,height

eg. "0,0,669,479"

For Lua, returns a table containing:

top=(value)
height=(value)
left=(value)
width=(value)

see_also:
MoveWorldWindow MoveNotepadWindow MoveMainWindow GetNotepadWindowPosition GetMainWindowPosition GetWorldWindowPositionX MoveWorldWindowX

lua_notes:
In Lua it returns a table with four entries, like this:

top 0
height 479
left 0
width 669

Lua has an optional argument which is the window number to examine. The first (main) window is window 1.

If you do Window -> New Window then you will get more windows, these will be 2, 3, 4 and so on.

You can use GetInfo (235) to find how many windows are currently open.

If you specify a window that does not exist you will get a nil result.

------------------

When using Lua the function GetWorldWindowPosition can take an optional second argument. If true, the world window position is reported in screen co-ordinates (that is, relative to the top-left corner of your monitor) rather than the default of relative to the main MUSHclient window. This lets you write plugins (like graphical status bars) that know where the world window is actually on the screen, so they can be drawn to be nearby.

------------------

When using Lua the function GetWorldWindowPosition can take an optional third argument. If true, a different method of calculating the window position is used (calling GetWindowRect rather than GetWindowPlacement). This method gives a more accurate result if you use "Aero Snap" under Windows 7 or higher. However it may return inaccurate results if the window is minimized.

eg.

GetMainWindowPosition (true)

The default is false, the original behaviour.

Also the top and left positions, when the third argument is true, are slightly different to those supplied when it is false, for reasons that are not completely obvious, but might be the height of the title bar and the width of the scroll bars.


name: GetNotepadWindowPosition
prototype: BSTR GetNotepadWindowPosition(BSTR Title);
summary: Returns the position and size of the specified notepad window
vb_example: Note GetNotepadWindowPosition ("my_notepad")
java_example: Note (GetNotepadWindowPosition ("my_notepad"))
type_of_object: Method
doc_name: info
lua_example: table.foreach (GetNotepadWindowPosition ("my_notepad"), print)
description:
This function returns the size of the specified notepad's window, in pixels.

For normal scripting languages these return a string, like this: "66,66,637,356". For Lua, see below.

return_value:
Returns a string in the form:

left,top,width,height

eg. "66,66,637,356"

For Lua, returns a table containing:

top=(value)
height=(value)
left=(value)
width=(value)

If the nominated notepad window does not exist, returns the empty string.

In Lua, if the notepad window does not exist, returns nil.

see_also:
MoveWorldWindow MoveNotepadWindow MoveMainWindow GetWorldWindowPosition GetMainWindowPosition GetNotepadList

lua_notes:
In Lua it returns a table with four entries, like this:

top 66
height 356
left 66
width 637

If the notepad window does not exist, returns nil.


name: UdpSend
prototype: long UdpSend(BSTR IP, short Port, BSTR Text);
summary: Sends a packet over the network using the UDP protocol
vb_example: UdpSend "10.0.0.3", 4111, "magic,textcolour,5555"
java_example: UdpSend ("10.0.0.3", 4111, "magic,textcolour,5555")
type_of_object: Method
see_also: UdpListen UdpPortList GetUdpPort
lua_example: UdpSend ("10.0.0.3", 4111, "magic,textcolour,5555")
description:
This sends a single UDP (User Datagram Protocol) packet over the network, to the specified IP address and port.

The intention here is to communicate with other programs, such as the status-bar stand-alone program using UDP to send short messages.

You can broadcast to more than one PC by using a broadcast address.

The address must be a dotted number, not a name (eg. 10.0.0.8)

return_value:
If the packet was sent successfully, zero is returned. 

If the address could not be decoded, -1 is returned;

For other socket errors the Windows socket error number.


name: UdpListen
prototype: long UdpListen(BSTR IP, short Port, BSTR Script);
summary: Listens for incoming packets using the UDP protocol
vb_example: UdpListen "0.0.0.0", 4111, "MyScript"
java_example: UdpListen ("0.0.0.0", 4111, "MyScript")
type_of_object: Method
see_also: UdpSend UdpPortList GetUdpPort
description:
This lets you set up a plugin script function that will be called whenever a UDP packet arrives on the specified port.

This lets you set up a separate program which can communicate with MUSHclient by sending it UDP packets.

The maximum size message that can be received is 999 bytes. In practice, attempting to receive more than 512 bytes may fail due to fragmentation over the network. Note that UDP packets are not guaranteed to arrive, or may arrive out of order. If UDP packets are fragmented by routers, and any fragment does not arrive, then the whole packet is discarded.

UDP is best used in situations where smallish amounts of data, which are not critical that they arrive at all, or in sequence, need to be sent. An example would be something like player or mob status information, where if one packet is lost, another would arrive shortly afterwards, and the loss of a single packet would be an inconvenience, not a disaster.

To listen to messages from any address use the address "0.0.0.0".

The address must be a dotted number, not a name (eg. "10.0.0.8")

You can cancel a listener by calling this function (for a previously-setup port) with an empty script name.

The script must be in a plugin, and be defined to accept a single string (which is the text that arrives in the UDP packet). For example, in Lua:

function listener (s)
  --  process UDP packet "s" here
end -- listener

return_value:
eNotAPlugin: This must be called from a plugin
eBadParameter: The port is already in use by another plugin, or the UDP socket could not be created
eNoNameSpecified: No script name was specified
eOK: succeeded

lua_example:
-- listening function in plugin:
function listener (s)
  ColourNote ("white", "blue", "Got UDP packet: " .. s)
end -- listener 

-- set up listener
require "check"
check (UdpListen ("0.0.0.0", 4111, "listener"))


name: NotepadColour
prototype: long NotepadColour(BSTR Title, BSTR TextColour, BSTR BackgroundColour);
summary: Changes the text and background colour of the selected notepad window
vb_example: NotepadColour "test", "#FAEBD7", "#FFB6C1" NotepadColour "test", "whitesmoke", "saddlebrown"
java_example: NotepadColour ("test", "#FAEBD7", "#FFB6C1"); NotepadColour ("test", "whitesmoke", "saddlebrown");
type_of_object: Method
doc_name: notepad
lua_example: NotepadColour ("test", "#FAEBD7", "#FFB6C1") NotepadColour ("test", "whitesmoke", "saddlebrown")
description:
This lets you set the text and background colour of an open notepad window. 

eg.

AppendToNotepad ("test", "but does it get goat's blood out?") -- create window
NotepadColour ("test", "whitesmoke", "saddlebrown") -- change its colour

The colours are specified by colour name - you can use the MUSHclient colour picker to see all possible colour names, or type: world.Debug ("colours"). 

You can also specify colours in HTML format, like this:

NotepadColour ("test", "#FAEBD7", "#FFB6C1")

return_value:
0 = Could not do it (eg. that notepad does not exist, one of those colours do not exist)
1 = Colours changed OK.

see_also:
MoveMainWindow MoveWorldWindow GetMainWindowPosition GetWorldWindowPosition GetNotepadWindowPosition NotepadFont NotepadColour GetNotepadList NotepadReadOnly


name: NotepadFont
prototype: long NotepadFont(BSTR Title, BSTR FontName, short Size, short Style, short Charset);
summary: Changes the font and style of the selected notepad window
vb_example: NotepadFont "test", "Comic Sans MS", 11, 0, 0
java_example: NotepadFont ("test", "Comic Sans MS", 11, 0, 0);
return_value: 0 = Could not do it (eg. that notepad does not exist) 1 = Font and style changed OK.
type_of_object: Method
doc_name: notepad
lua_example: NotepadFont ("test", "Comic Sans MS", 11, 0, 0)
lua_notes: The charset argument is optional and defaults to zero.
description:
This lets you change the font, font size, style, and character set of the font for an open notepad window.

eg.

NotepadFont ("test", "Comic Sans MS", 11, 0, 0)

The arguments are:

notepad name
font name
font size 
style bits
character set

If the font name is empty, then the font is unchanged.

If the font size is zero, then the font size is unchanged. The font size is in points.

The style should be a combination of the numbers below (zero is just plain text). For instance, bold and italic would be 3.

Style bits:

1 = bold
2 = italic
4 = underline
8 = strikeout

see_also:
MoveMainWindow MoveWorldWindow GetMainWindowPosition GetWorldWindowPosition GetNotepadWindowPosition NotepadColour GetNotepadList


name: MtSrand
prototype: void MtSrand(long Seed);
summary: Seed the Mersenne Twister pseudo-random number generator
description: This seeds the MT generator with the given number, which is a 32-bit number.
vb_example: MtSrand 12345
java_example: MtSrand (12345)
return_value: Nothing.
type_of_object: Method
see_also: MtRand
doc_name: utils
lua_example: MtSrand (12345) MtSrand { 88, 44, 95, 1234, 82343, 44853454 } -- see remarks below
lua_notes:
You can also seed the Mersenne Twister with a table of seeds, rather than a single number. 

This is because, although the MT generator has a period of 2^19937-1 (that is, the number of iterations before it repeats itself), the initial seeding is only a single number of 2^32 bits. 

Thus there are effectively only 2^32 (4294967296) possible starting states for the generator. 

However by initialising with an array of seeds you can effectively seed the generator to many different states.

The restrictions on using the array of seeds are:

* It only applies to Lua
* The seeds must be numbers (or convertible to numbers)
* There must be at least one number
* They must be an ordinary Lua vector-style table. That is, the key of the first seed is 1, the key of the second is 2, and so on.
* The seed numbers should be integers in the range 0 to 4294967296

Example:

t = { 1234, 5678, 9876, 5432 }
MtSrand (t) -- seed with table of seeds
MtSrand (8888) -- seed with single seed

The MT internal state consists of a vector of 624 32-bit numbers. 

You can supply any size table, if it is less than 624 entries, effectively the ones you supply are repeated through the state table. 

If you supply more they will be XOR'd with the earlier values. Probably 624 numbers is the maximum useful amount you can supply.


name: MtRand
prototype: double MtRand();
summary: Returns pseudo-random number using the Mersenne Twister algorithm
vb_example: Note MtRand
java_example: Note (MtRand ())
type_of_object: Method
see_also: MtSrand
doc_name: utils
description:
This returns a pseudo-random number in the range 0 to 1 (however excluding 1) as a "double" (floating-point number). Thus you can generate a number in any range by multiplying the result by the range you want.

eg.

print (math.floor (MtRand () * 5)) - returns 0 to 4

See below in the Lua section for an example of doing coin flips.

Note that the MT generator is "global" to all of MUSHclient. If you are trying to reproduce a sequence, then you cannot rely on a sequence staying stable from one script call to another (since another script, or another world or plugin, might also use random numbers).

This (Lua) script here, for example, would generate a million random numbers, and put them into a table for later use:

nums = {}  -- empty table

MtSrand (1234567) -- start with a known seed

for j = 1, 1000000 do
  table.insert (nums, MtRand ())
end

This took about a second to execute on my PC.

Over a run of 10,000,000 coins flips it seemed pretty accurate, giving 5,000,625 heads and 4,999,375 tails (in other words, around 50.00625% heads).

Example (in Lua) of rolling a 6-sided die:

for i = 1, 100 do
  Tell (math.floor (MtRand () * 6) + 1, " ") 
end

In the above example, multiplying by 6 gives a number in the range 0 to 5, and then we add 1 to make it 1 to 6.


For more details about the Mersenne Twister see:

http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/emt.html

return_value:
A pseudo-random number in the range [0 to 1). In other words, zero might be returned, however 1 will not be.

To put it another way, the returned number is:

>= 0 and < 1

lua_example:
heads = 0
tails = 0

for j = 1, 1000000 do
  i = math.floor (MtRand () * 2)
  if i == 0 then
    heads = heads + 1
  else
    tails = tails + 1
  end  -- if
end  -- for

print ("heads = ", heads) --> 498893
print ("tails = ", tails) --> 501107


name: SetChanged
prototype: void SetChanged(BOOL ChangedFlag);
summary: Sets or clears the "document has changed" flag
vb_example: SetChanged vbTrue
java_example: SetChanged (true)
return_value: Nothing.
type_of_object: Method
doc_name: info
lua_example: SetChanged (true)
lua_notes: The argument is optional, and defaults to true.
description:
Use this function to set or clear the "world has changed" flag. If this flag is set, you will be asked to save it. If clear, you will not be asked to save it.


name: UdpPortList
prototype: VARIANT UdpPortList();
summary: Returns an array of all the UDP ports in use by this world
type_of_object: Method
see_also: UdpSend UdpListen GetUdpPort
doc_name: info
lua_example: -- show all ports for _, v in pairs (UdpPortList()) do Note (v) end
description:
Returns a variant array of all the UDP ports that are being listened to by plugins for this world. eg.

4223
4224

vb_example:
dim portList

portList= world.UdpPortList

If Not IsEmpty (portList) Then
  
  For Each v In portList
    world.note v 
  Next

End If

return_value:
If there are no ports in use then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the port numbers in use.

Use "lbound" and "ubound" to find the bounds of the array of variables (ie. the number of ports in the list).


name: MoveWorldWindowX
prototype: void MoveWorldWindowX(long Left, long Top, long Width, long Height, short Which);
summary: Move and resize a specific world window
vb_example: MoveWorldWindowX 1, 1, 640, 480, 2 ' move window 2
java_example: MoveWorldWindowX (1, 1, 640, 480, 2)
return_value: None.
type_of_object: Method
doc_name: utils
lua_example: Not available in Lua - use MoveWorldWindow with a 5th argument instead.
lua_notes: Lua has an optional 5th argument to MoveWorldWindow which is the window number to move.
description:
This function moves and resizes one of the current world's windows.

Specify the left and top co-ordinates in pixels.

Specify the width and height of the window in pixels.

Note that if you move the window off the screen (eg. to -1000, -1000) it will become invisible.

No checking is performed on the arguments to this function.

The co-ordinates are relative to the client area of the main MUSHclient window.

In other words, position 1, 1 is the very top-left corner of the MUSHclient frame window.

The first window is window number 1, the second one is 2, and so on. You create new windows by using Window menu -> New Window.

see_also:
MoveMainWindow MoveNotepadWindow GetMainWindowPosition GetWorldWindowPosition GetNotepadWindowPosition MoveWorldWindow GetWorldWindowPositionX SetWorldWindowStatus SetToolBarPosition


name: GetWorldWindowPositionX
prototype: BSTR GetWorldWindowPositionX(short Which);
summary: Returns the position and size of a specific world window
vb_example: Note GetWorldWindowPositionX (2)
java_example: Note (GetWorldWindowPositionX (2))
return_value: Returns a string in the form: left,top,width,height eg. "0,0,669,479"
type_of_object: Method
doc_name: info
lua_example: Not available in Lua - use GetWorldWindowPosition with a window number argument instead.
lua_notes: Lua has an optional argument to GetWorldWindowPosition which is the window number to get.
description:
This function returns the size of one of the current world's window, in pixels.

For normal scripting languages these return a string, like this: "0,0,669,479". 

The first window is window number 1, the second one is 2, and so on. You create new windows by using Window menu -> New Window.

see_also:
MoveWorldWindow MoveNotepadWindow MoveMainWindow GetNotepadWindowPosition GetMainWindowPosition GetWorldWindowPosition MoveWorldWindowX


name: SetEntity
prototype: void SetEntity(BSTR Name, BSTR Contents);
summary: Sets the value of an MXP entity
vb_example: SetEntity "foo", "bar"
java_example: SetEntity ("foo", "bar");
return_value: Nothing.
type_of_object: Method
see_also: GetVariable GetEntity SetVariable
doc_name: info
lua_example: SetEntity ("foo", "bar)
description:
Sets the value of an MXP (custom) entity.

If the supplied contents is the empty string, the entity is deleted.

If the entity already exists it is replaced.

No checking is made for the name or contents strings' values (for example, they might be just spaces).

It is up to you to use sensible values.

Custom entities are stored separately from standard entities. Thus you cannot replace, for example, the "lt" entity.

lua_notes:
The contents are optional. If omitted they default to the empty string, and thus the named entity will be deleted.


name: GetXMLEntity
prototype: BSTR GetXMLEntity(BSTR Entity);
summary: Retrieves the value of a standard entity
vb_example: world.Note world.GetXMLEntity("lt")
java_example: world.Note (world.GetXMLEntity("lt"));
perl_example: $world->Note (world.GetXMLEntity("lt"));
type_of_object: Method
see_also: GetVariable SetEntity GetEntity
python_example: world.Note (world.GetXMLEntity ("lt"))
doc_name: info
lua_example: Note (GetXMLEntity ("lt"))
description:
Returns the value of a standard XML/MXP (HTML) entity.

To get user (server defined) entities use GetEntity.

Entity names are the standard HTML ones. There is a list on this page:

http://www.gammon.com.au/mushclient/mxpentities.htm

You can also use entities in the form: #nnn where nnn is a decimal number in the range 32 to 255.

You can also use entities in the form: #xhh where hh is a hexadecimal number in the range 20 to FF.

The entity name should *not* include the leading ampersand or trailing semicolon that you use in XML, MXP or HTML.

return_value:
The contents of the specified entity, or an empty string if no such entity is found, or the syntax is invalid (eg. #999).


name: GetUdpPort
prototype: long GetUdpPort(long First, long Last);
summary: Find a free port for UDP listening
vb_example: Note GetUdpPort (4000, 4100)
java_example: Note (GetUdpPort (4000, 4100))
type_of_object: Method
see_also: UdpSend UdpPortList UdpListen
lua_example: free_port = GetUdpPort (4000, 4100)
description:
This function finds a free port for use by MUSHclient as a UDP listener. It operates by scanning all open worlds for ports in use by UdpListen. It then works through the range you specify to find one that is not in use.

However this test is only for port used by MUSHclient. There is no guarantee that the port is not in use by another application.

The intention is for plugin writers to use it to find a port in a range (say, 4000 to 4100) which is not in use by another plugin, or the same plugin in another world.

The First and Last arguments are port numbers, inclusive, that you wish to be scanned. eg. GetUdpPort (4000, 4100) would find a port in the range 4000 to 4100 inclusive.

The port numbers must be greater than zero and less than 65535. Also the last port number must be greater than or equal to the first port number.

return_value:
0 : No free port was found in the specified range, or the range was invalid.

non-zero : A port not in use by MUSHclient's UdpListen function.


name: BroadcastPlugin
prototype: long BroadcastPlugin(long Message, BSTR Text);
summary: Broadcasts a message to all installed plugins
vb_example: world.BroadcastPlugin 100, "Some message"
java_example: world.BroadcastPlugin (100, "some message");
perl_example: $world->BroadcastPlugin (100, "some message");
return_value: The number of plugins that had an OnPluginBroadcast handler.
type_of_object: Method
see_also: PluginSupports GetPluginID GetPluginList GetPluginInfo LoadPlugin IsPluginInstalled CallPlugin
python_example: world.BroadcastPlugin (100, "some message")
doc_name: plugins
lua_example: BroadcastPlugin (100, "some message")
lua_notes: The Text parameter is optional, and defaults to an empty string.
description:
Broadcasts the message to all installed plugins.

The intention here is for one plugin to catch an event and "notify" all other plugins of that event.

You supply 2 arguments, a number and a string.

The number is intended to be a "message number", to indicate the type of message (eg. trigger has fired = 1, alias matched = 2).

The string is intended to allow you to supply free-format data to the plugin.

All installed plugins are checked for a function OnPluginBroadcast. If present, it is called with 4 arguments:

1 - the message number (supplied above).

2 - the ID of the calling plugin, or an empty string if BroadcastPlugin was called from the main script file.

3 - the name of the calling plugin, or an empty string if BroadcastPlugin was called from the main script file.

4 - the Text argument (supplied above)

An example of a plugin handler might be (in Lua):


function OnPluginBroadcast (msg, id, name, text)
  Note ("msg = " .. msg)
  Note ("id = " .. id)
  Note ("name = " .. name)
  Note ("text = " .. text)
end


The calling plugin ID and name are supplied so that plugin writers can verify which plugin originated a particular message. This cannot be spoofed as it is supplied automatically by MUSHclient.

Thus, a sensible test might be for a plugin that incorporates an OnPluginBroadcast handler, to test the id supplied to match the id of the plugin that it expects to be doing the broadcast.


name: PickColour
prototype: long PickColour(long Suggested);
summary: Invokes the MUSHclient colour picker dialog
vb_example: newcolour = PickColour (255)
java_example: newcolour = PickColour (255);
perl_example: newcolour = $world->PickColour (255)
return_value: The chosen colour, or -1 if the dialog box was dismissed.
type_of_object: Method
python_example: newcolour = world.PickColour (255);
doc_name: colours
lua_example: newcolour = PickColour (255)
description:
This lets you call the MUSHclient colour picker from within a script. Note that doing this will pause script execution while the dialog is active, and is not recommended for scripts that should run to completion quickly.

eg.

  newcolour = PickColour (254)

You supply an existing colour as the starting point, or -1 if none is required, and the function returns the chosen colour, or -1 if the dialog was cancelled. Note that -1 is not a valid colour.

see_also:
ColourNameToRGB CustomColourBackground BoldColour CustomColourText Debug NormalColour NoteColourBack NoteColourFore NoteColourName NoteColourRGB MapColour RGBColourToName


name: TraceOut
prototype: void TraceOut(BSTR Message);
summary: Outputs the supplied message to the world Trace
vb_example: TraceOut "debug point 3"
java_example: TraceOut ("debug point 3")
return_value: Nothing.
type_of_object: Method
see_also: Trace
doc_name: utils
lua_example: TraceOut ("debug point 3")
lua_notes: You can supply multiple arguments, which are concatenated together.
description:
If tracing is enabled for this world, the supplied string will be output to the trace destination. Normally this would be by world.Note, however if you are using a plugin with OnPluginTrace inside it, then it will be sent to there instead.

eg.

TraceOut ("debug point 3")


name: ErrorDesc
prototype: BSTR ErrorDesc(long Code);
summary: Converts a MUSHclient script error code into an human-readable description
vb_example: result = SetVariable ("***", "abc") if result <> 0 then Note ErrorDesc (result) end if
java_example: result = SetVariable ("***", "abc"); if (result != 0) { Note (ErrorDesc (result)) }
type_of_object: Method
doc_name: utils
lua_example: result = SetVariable ("***", "abc"); if result ~= 0 then Note (ErrorDesc (result)) end -- if
description:
This function converts a return code (such as 30008) into a human-readable form ("The name of this object is invalid").

The purpose is to allow scripts which fail to detect the reason and display it in human-readable form.

eg. (in VBscript)

result = SetVariable ("***", "abc")

if result <> 0 then
  Note ErrorDesc (result)
end if

return_value:
A string containing the code converted to human-readable form, or the supplied argument converted to a string if the code is not in MUSHclient's internal list of error codes. At present, the range of codes that will be converted is 0, and 30001 to 30062.

lua_notes:
In Lua, it is simpler to use the error_desc table, which is available in earlier versions of MUSHclient also.

eg.

result = SetVariable ("***", "abc");

if result ~= 0 then
  Note (error_desc [result])
end -- if

This is simply a table-lookup in Lua, rather than a call to a MUSHclient function.


name: PasteCommand
prototype: BSTR PasteCommand(BSTR Text);
summary: Pastes text into the command window, replacing the current selection
vb_example: previous = PasteCommand ("swordfish")
java_example: PasteCommand ("swordfish");
perl_example: $world->PasteCommand ("swordfish");
return_value: The previously selected text, if any.
type_of_object: Method
see_also: SetCommand Accelerator
python_example: PasteCommand ("swordfish")
doc_name: send
lua_example: previous = PasteCommand ("swordfish")
description:
This pastes the supplied text into the command window, which does not have to be empty (unlike SetCommand) at the current cursor position, replacing any selection. It returns the text that it replaced, if any.

eg.

Command window reads:

go north
^^

("go" is selected)

You execute:  s = PasteCommand ("walk")

Command window now reads:

walk north

s contains "go"

You could use this to make shortcut keys that paste frequently-used words into the command window.

For example:

/Accelerator ("Alt+N", "/PasteCommand 'swordfish'")

Now, whenever you hit Alt+N the word "swordfish" is pasted into the command window, replacing the current selection, or at the cursor.


name: Help
prototype: void Help(BSTR Name);
summary: Shows help for a script function, or a list of functions
vb_example: Help "colournote"
java_example: Help ("colournote")
return_value: Nothing.
type_of_object: Method
doc_name: utils
lua_example: Help "colournote" Help "lua io"
lua_notes: The argument is optional.
description:
This function is to help scripters quickly get information about script functions.

You can optionally supply a string argument. If the argument exactly matches a script function (case is not important) then the help for that function is shown.

eg.

/Help "colournote"  --> show help for world.ColourNote

If the argument partially matches a script function, then the "functions help" dialog box will be displayed with that text as the filter.

eg.

/Help "trigger"  --> show list of trigger-related functions


If the argument is empty then all script functions will be displayed.

The argument "lua" is a special case, and will show the help for all Lua-specific functions in MUSHclient.

eg.

/Help "lua"

You can also get help on Lua libraries by supplying "lua x" where x is the first letter of one of the standard Lua libraries, namely:

b - Base  (not in a library)    
c - Coroutines
d - Debug     
i - Io        
m - Math      
o - Os        
p - Package   
r - Rex
s - String    
t - Table
u - Utils

You can type more letters if you want, but only the first 5 are checked. eg.

/Help "lua io"  --  (same as /Help "lua i")

In addition it also recognises:

/Help "lua bc" -- bc (bignum) library


name: Simulate
prototype: void Simulate(BSTR Text);
summary: Simulate input from the MUD, for debugging purposes
vb_example: Simulate "Exits: north" + vbCrLf
java_example: Simulate ("Exits: north\n");
return_value: Nothing.
type_of_object: Method
see_also: Debug
doc_name: utils
lua_example: Simulate ("Exits: north\n")
lua_notes: You can supply multiple arguments, which are concatenated together.
description:
The argument to this function is supplied to MUSHclient as if it had been sent from the MUD. This is intended for debugging triggers etc, similar to the Game -> Test Trigger menu option.

This should be used with caution inside scripts. If you simulate input inside a trigger, the input causing another trigger to fire, you are likely to get a stack overflow.

An example of using it would be to bind it to a keystroke (like F11), so that if you are testing a trigger that matches on:

Exits: north

... then you might do this:

Accelerator ("F11", "/Simulate 'Exits: north\n' ")


name: ResetIP
prototype: void ResetIP();
summary: Resets the cached IP address of the world and proxy server
vb_example: ResetIP
java_example: ResetIP ()
return_value: Nothing.
type_of_object: Method
see_also: Connect Disconnect
lua_example: ResetIP ()
description:
Call this function to reset the internal copy of the world's IP address, saved after looking up its domain name.

This would be useful if you connect to worlds that frequenly change their address, otherwise the old (cached) one would be used when you connect to the world the second and subsequent times.


name: AddSpellCheckWord
prototype: long AddSpellCheckWord(BSTR OriginalWord, BSTR ActionCode, BSTR ReplacementWord);
summary: Adds a word to the user spell check dictionary
type_of_object: Method
see_also: SpellCheck SpellCheckCommand
doc_name: spellcheck
lua_notes: The third argument (replacement word) is optional and defaults to an empty string.
description:
This lets you add a word to the spell checker "user dictionary" from within a script.

Usage:

result = AddSpellCheckWord (original_word, action, replacement)

original_word = word to match on

action = one of the following single characters (case-sensitive):

'a' = The word should be unconditionally substituted for another word; the substitution should use the case pattern as listed in the lexicon.

'A' = The word should be unconditionally substituted for another word; the substitution should use the case pattern of the original word.

'c' = The word should be conditionally substituted for another word; the substitution should use the case pattern as listed in the lexicon.

'C' = The word should be conditionally substituted for another word; the substitution should use the case pattern of the original word.

'e' = The word should be treated as misspelled by the spell checker, even if it is defined in other lexicons.

'i' = The word should be ignored (skipped) because it is considered correctly spelled.

replacement = the word to replace (or suggest a replacement for) the original word

eg.

AddSpellCheckWord ("foo", "A", "bar")  --> convert "foo" to "bar"
AddSpellCheckWord ("colour", "i", "")  --> "colour" is spelt correctly

vb_example:
AddSpellCheckWord "foo", "A", "bar"  ' convert "foo" to "bar"
AddSpellCheckWord "colour", "i", ""  ' "colour" is spelt correctly

return_value:
eSpellCheckNotActive - spell checker not enabled or could not be opened

eBadParameter - 

original_word not supplied or too long (more than 63 characters); or 
replacement word too long (more than 63 characters); or
error returned from spell-check engine

eUnknownOption - action code not in the above list

eOK - did it OK

lua_example:
AddSpellCheckWord ("foo", "A", "bar")  --> convert "foo" to "bar"
AddSpellCheckWord ("colour", "i", "")  --> "colour" is spelt correctly


name: GetCustomColourName
prototype: BSTR GetCustomColourName(short WhichColour);
summary: Gets the name of a custom colour
vb_example: Note GetCustomColourName (5)
java_example: Note (GetCustomColourName (5));
perl_example: $world->Note($world->GetCustomColourName (5));
type_of_object: Method
see_also: CustomColourBackground NormalColour BoldColour CustomColourText SetCustomColourName
python_example: world.Note(world.GetCustomColourName (5))
doc_name: colours
lua_example: Note(GetCustomColourName (5))
description:
Use this to get the name of one of the 16 custom colours in the world's custom colour configuration. You must specify *which* colour you want to get/set, in the range 1 to 16.

return_value:
It returns the name of the specified custom colour, or an empty string if the colour number is out of the range 1 to 16.


name: OpenBrowser
prototype: long OpenBrowser(BSTR URL);
summary: Opens a supplied URL in your default web browser
vb_example: OpenBrowser "http://www.mushclient.com"
java_example: OpenBrowser ("http://www.mushclient.com")
perl_example: $world->OpenBrowser ("http://www.mushclient.com");
type_of_object: Method
see_also: Open
doc_name: world
lua_example: OpenBrowser ("http://www.mushclient.com")
description:
Opens the URL you supply using the default web browser for this PC.

The URL must start with one of the following strings (not case-sensitive):

http://
https://
mailto:

return_value:
eBadParameter - the URL was either empty or did not start with "http://", "https://", or "mailto:".

eCouldNotOpenFile - an error code was returned by Windows when attempting to open the web browser

eOK - successfully opened


name: DeleteLines
prototype: void DeleteLines(long Count);
summary: Clears some recent lines from the output window.
vb_example: world.DeleteLines (10)
java_example: world.DeleteLines(10);
perl_example: $world->DeleteLines(10);
return_value: Nothing.
type_of_object: Method
see_also: DeleteOutput
python_example: world.DeleteLines (10)
lua_example: DeleteLines(10)
description:
Clears 'Count' lines from the output window, starting at the end (most recently-displayed).

This allows you to script the omission of recently-received lines (for example, in a multi-line trigger).

All line types are omitted (whether received from the MUD, command input, or Note lines). A line is counted as a physical line on the screen, it does not necessarily end in a newline character.

Warning - do NOT call DeleteLines from a trigger, alias or timer using send-to-script. For design reasons this will not work. In version 3.76 you will cause the client to crash if you do this. In version 3.77 upwards it will silently fail (ie. do nothing).

If you want to call DeleteLines from a trigger you must call a function in your script file (or plugin script), not directly from send-to-script.

You can also not call it from a plugin callback.


name: NotepadSaveMethod
prototype: boolean NotepadSaveMethod(BSTR Title, short Method);
summary: Changes the save method for this notepad window
vb_example: NotepadSaveMethod "test", 1
java_example: NotepadSaveMethod ("test", 1);
type_of_object: Method
see_also: SaveNotepad GetNotepadList NotepadReadOnly
doc_name: notepad
lua_example: NotepadSaveMethod ("test", 1)
description:
This lets you change the save method for an open notepad window.

The first argument is the title of an existing notepad window. The second argument is one of the following 3 numbers:

0 - Use default method (same as if this function had not been called)
1 - Always offer to save this window if the contents have changed
2 - Never offer to save this window if the contents have changed

eg.

NotepadSaveMethod ("test", 1)

The following notepad window types normally close without offering to save:

Line Info         
MXP debug  (depending on MXP options)
Packet Debug       
Plugin Info     
XML comments       
World Load Error    

You could use this to force the saving of something like Packet Debug, or inhibit the saving of a notepad window you created yourself.

return_value:
0 = Could not do it (eg. that notepad does not exist, or option out of range)
1 = Option changed OK.


name: ChangeDir
prototype: long ChangeDir(BSTR Path);
summary: Changes the MUSHclient working directory
vb_example: ChangeDir GetInfo (66)
return_value: 0 - Did not change directory 1 - Did it OK
type_of_object: Method
see_also: GetInfo
doc_name: utils
lua_example: ChangeDir (GetInfo (66))
description:
This lets you change the current working directory used by MUSHclient. This is useful for situations (like plugins) where you want to load files relative to the plugin location but are unsure if the working directory is at the plugin location. eg.

  ChangeDir (GetInfo (66))  --> ensure directory is MUSHclient.exe directory

Note that some actions (like opening world files) may change the directory (eg. to the world file directory) as a side-effect.


name: SendPkt
prototype: long SendPkt(BSTR Packet);
summary: Sends a low-level packet of data to the MUD
vb_example: SendPkt Chr(255) & Chr (252) & Chr (31) ' IAC WONT NAWS
return_value: eWorldClosed : The world is closed eOK: Sent OK
type_of_object: Method
see_also: Note LogSend SendPush Execute SendImmediate Queue SendNoEcho Send
doc_name: send
lua_example: SendPkt (string.char (255, 252, 31)) -- IAC WONT NAWS
description:
This sends the specified text to the world. 

A newline is not appended to it.

If the text contains the IAC character (0xFF) a second IAC character is NOT appended to it (as normally happens).

The text does not go through the OnPluginSend plugin callback, nor through the OnPluginSent callback. 

The text is not echoed to the screen.

It is intended only for low-level sending of data for things like telnet negotiation options.

lua_notes:
The data may include imbedded null characters (0x00) as the Lua string is not tested for being null-terminated.


name: Metaphone
prototype: BSTR Metaphone(BSTR Word, short Length);
summary: Returns the metaphone code for the supplied word
vb_example: Note Metaphone ("swordfish", 4)
return_value: The converted code, or two codes separated by commas.
type_of_object: Method
see_also: EditDistance
doc_name: utils
lua_example: Note (Metaphone ("swordfish"))
lua_notes: The length is optional and defaults to 4. Also available as utils.metaphone.
description:
Returns a code indicating the "sound" of the supplied word. This is intended for use in a spell checker or similar to find words that sound the same or similar.

For example: 

swordfish = SRTF,XRTF
Gammon = KMN
gamon = KMN
gamin = KMN
Cameron = KMRN
bruise = PRS
Bruce = PRS

You supply the word to be converted, and a length indicating the maximum size code you want returned.

This uses the "double metaphone" algorithm written by Lawrence Philips. It returns either a single metaphone (like KMN for Gammon) or two metaphones where an alternative pronunciation could be considered. Thus in the case of "swordfish" you could store that under SRTF or XRTF and consider both sound-alikes. If there is a comma present, then you know you had an alternative returned.

Because of this, if you specify a 4 character length, you might get back 9 characters (two 4-character metaphones, plus a comma).

Apart from the comma, only the following letters will be returned:

0 A F H J K L M N P R S T X 

(First one is a zero indicating the "th" sound).

For a fast lookup, you could map each letter into a hex digit and then combine them into a single 16-bit number, eg.

0 = 0
A = 1
F = 2
H = 3
J = 4
K = 5
L = 6
M = 7
N = 8
P = 9
R = A
S = B
T = C
X = D


name: EditDistance
prototype: long EditDistance(BSTR Source, BSTR Target);
summary: Returns the Levenshtein Edit Distance between two words
vb_example: Note EditDistance ("food", "fod") ' --> 1 Note EditDistance ("food", "fodder") ' --> 3
return_value: The edit distance between the two numbers.
type_of_object: Method
see_also: Metaphone
doc_name: utils
lua_example: Note (EditDistance ("food", "fod")) --> 1 Note (EditDistance ("food", "fodder")) --> 3
lua_notes: Also available as utils.edit_distance.
description:
Returns the "edit distance" between two words.

This is intended for use in the spell checker or similar applications, where you need to know how close one word is to another.

The Levenshtein distance between two strings  is defined as the minimum number of edits needed to transform one string into the other, with the allowable edit operations being insertion, deletion, or substitution of a single character.

For example, the Levenshtein distance between "kitten" and "sitting" is 3, since the following three edits change one into the other, and there is no way to do it with fewer than three edits:

   1. kitten --> sitten (substitution of 's' for 'k')
   2. sitten --> sittin (substitution of 'i' for 'e')
   3. sittin --> sitting (insert 'g' at the end).


name: Transparency
prototype: boolean Transparency(long Key, short Amount);
summary: Sets the transparency of the main MUSHclient window under Windows XP
return_value: On success, returns true. On failure, returns false (eg. under Windows 95).
type_of_object: Method
see_also: ColourNameToRGB
doc_name: utils
description:
Under Windows XP or later operating systems, you can make the MUSHclient window semi-transparent, so that the underlying windows "show through". Under Windows NT/2000/95/98/ME this function does nothing.

Key: specifies the transparency colour key to be used when composing the layered window. All pixels painted by the window in this color will be transparent. This is an RGB code, you can use ColourNameToRGB to convert a name to RGB.

If the key is -1 then there is no colour key.

Amount: the amount of transparency for other colours, in the range 0 to 255. If outside this range the number will be coerced into it.

WARNING

Drawing transparent windows may slow down the program, as the operating system has to render to an off-screen bitmap and copy to the main window. This slow-down may not be obvious on fast PCs.

vb_example:
Transparency -1, 127  ' Make everything 50% transparent
Transparency 0, 255   ' Black is transparent, everything else is full intensity

lua_example:
Transparency (-1, 127) -- Make everything 50% transparent
Transparency (0, 255)  -- Black is transparent, everything else is full intensity
Transparency (ColourNameToRGB ("red"), 64)  -- Red is transparent, everything else is 25% transparent


name: SpellCheckDlg
prototype: VARIANT SpellCheckDlg(BSTR Text);
summary: Spell checks an arbitrary string of text, invloking the spell-checker dialog
type_of_object: Method
see_also: SpellCheckCommand AddSpellCheckWord SpellCheck
doc_name: spellcheck
description:
This function lets you call the MUSHclient spell-checker from a script on any arbitrary text string.

Note that if the spell-check engine has not been initialised (eg. the DLL is not present, or the spell check dictionary is not there), it returns the Empty variant (or nil in Lua).

You supply a string of text to be checked. 

The corrected string is returned, after the spellchecker dialog box has been invoked, as many times as necessary, for each misspelt word. If the dialog box is canclled them the NULL variant (or nil in Lua) is returned.

vb_example:
result = SpellCheckDlg _
  ("Twas brillig, and the slithy toves Did gyre and gimble in the the wabe")

if IsEmpty (result) then
  Note "Spell check cancelled"
else
  Note "Corrected string: " & result
end if

return_value:
If the spell checker is not available, or if the spellcheck dialog box is cancelled, an Empty variant (or nil in Lua).

Otherwise, the supplied string is returned, with any misspelt words corrected.

lua_example:
result = SpellCheckDlg  (
  "Twas brillig, and the slithy toves Did gyre and gimble in the the wabe")

print (type (result))

if result == nil then
  Note "Spell check cancelled"
else
  Note ("Corrected string: ", result)
end -- if


name: SetWorldWindowStatus
prototype: long SetScroll(long Position, BOOL Visible);
summary: Sets the scroll bar position, and hides or shows it
return_value: eOK - success
type_of_object: Method
see_also: GetInfo
lua_notes: The Visible flag is optional and defaults to true.
description:
This lets you do two things:

    * Hide the existing scroll bar if desired
    * Set the "scroll position" in the output window

The first feature (hiding the scroll bar) lets you, well, hide it, so that you can draw your own wherever you want (eg. with a themed miniwindow somewhere near where the text appears).

The second feature lets your code scroll the text around (so you can still use the existing output buffer) in response to the player clicking and dragging on "your" thumb, or arrows.

A position of -1 means "the end of the window" (which is the number of lines multiplied by the height of the font, minus the size of the output window).

A position of -2 means "no change".

You can use GetInfo (296) to find the current scroll-bar position (and thus add or subtract from it, to scroll up or down small amounts (like a line or a page).

You can use GetInfo (120) to find if the scroll-bar is currently hidden or not.

The existing code adds the font height (GetInfo (212)) to the current scroll position to scroll downwards a line, and subtracts it to scroll up a line.

To scroll up or down pages you need to find the size of the output window text rectangle, and add or subtract that.

lua_example:
SetScroll (0, false)  -- hide scroll bar, go to top of window
SetScroll (-1, false) -- hide scroll bar, go to end of window

SetScroll (-2, false) -- hide scroll bar, do not change position
SetScroll (-2, true)  -- show scroll bar, do not change position


name: SetCustomColourName
prototype: long SetCustomColourName(short WhichColour, BSTR Name);
summary: Sets the name of a custom colour
vb_example: SetCustomColourName(5, "combat")
java_example: SetCustomColourName(5, "combat");
perl_example: $world->SetCustomColourName (5, "combat");
type_of_object: Method
see_also: CustomColourBackground NormalColour BoldColour CustomColourText GetCustomColourName
python_example: world.SetCustomColourName (5, "combat")
doc_name: colours
lua_example: SetCustomColourName (5, "combat")
description:
Use this to set the name of one of the 16 custom colours in the world's custom colour configuration. 

You must specify *which* colour you want to get/set, in the range 1 to 16.

The name can be any string, which must be from 1 to 30 characters long.

return_value:
eOK - colour name set OK
eOptionOutOfRange - custom colour number out of the range 1 to 16
eNoNameSpecified - name was empty
eInvalidObjectLabel - name was more than 30 characters long


name: GetNotepadList
prototype: VARIANT GetNotepadList(boolean All);
summary: Gets the list of open notepads - returning their titles
vb_example: for each name in world.GetNotepadList world.Note name next
perl_example: foreach $item (Win32::OLE::in ($world->GetNotepadList)) { $world->note($item); }
type_of_object: Method
python_example: notepadlist = world.GetNotepadList if (notepadlist): for w in notepadlist : world.Note (w)
doc_name: notepad
lua_example: for k, v in pairs (GetNotepadList()) do Note (v) end
lua_notes: The argument "All" is optional, and defaults to false.
description:
Returns a variant array which is a list of all open notepad windows.

If more than one notepad has the same title you may get duplicates.

If the argument (All) is true, then all notepad windows for the MUSHclient application are returned.

If the argument is false, then only "related" notepads for the current world are returned. Related notepads are those created from the world (eg. by AppendToNotepad), and are not ones manually created (eg. by the player).

Note that most notepad-related functions only apply to related notepads - that is, ones that "belong" to the world calling them.

java_example:
notepadlist = new VBArray(world.GetNotepadList()).toArray();

if (notepadlist )  // if not empty
 for (i = 0; i < notepadlist.length; i++)
   world.note(notepadlist [i]);

return_value:
If there are no notepads open then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the titles of all the notepads. Use "ubound" to find the number of notepads in the list.

see_also:
SendToNotepad AppendToNotepad ActivateNotepad ReplaceNotepad SaveNotepad CloseNotepad GetNotepadLength GetNotepadText


name: TranslateDebug
prototype: long TranslateDebug(BSTR Message);
summary: Sends a debugging message to the localizing translator script
vb_example: world.TranslateDebug "display"
java_example: world.TranslateDebug ("display");
perl_example: $world->TranslateDebug ("display");
type_of_object: Method
python_example: world.TranslateDebug ("display")
doc_name: utils
lua_example: TranslateDebug ("general")
lua_notes: The Message argument is optional, and defaults an empty string.
description:
This sends a message to the translator script loaded at MUSHclient startup (if any). For example, if you had en.lua in the "locale" directory, it would be sent to the script space for that file (if EN was your locale).

The intention here is for that script to do things like monitor its performance (eg. count the number of times a string is translated) and display such counts when requested.

The message is passed to a function named "Debug" in the translator script (if found).

The function might look like this:

function Debug (message)

  if message == "display" then
    -- display counts
  elseif message == "reset" then
    -- reset counts 
  end -- if

end -- function Debug

return_value:
0 = called script OK
1 = script file not loaded (eg. no xx.lua file)
2 = function named Debug was not found in the script
3 = runtime error calling the function Debug


name: SendSpecial
prototype: long SendSpecial(BSTR Message, BOOL Echo, BOOL Queue, BOOL Log, BOOL History);
summary: Sends a message to the MUD with various options
vb_example: world.SendSpecial "go north", vbTrue, vbFalse, vbFalse, vbTrue
java_example: world.SendSpecial ("go north", true, false, false, true);
type_of_object: Method
see_also: Note LogSend Send SendPush
doc_name: send
lua_example: SendPush ("go north", true, false, true, false)
lua_notes: The boolean arguments are optional and default to false.
description:
This sends the specified text to the world. It is like typing it into the command window.

A newline character is appended to the text you supply, as MUD commands normally are terminated with a newline.

The text may include imbedded newlines. 

If the text has a trailing newline it is removed. In other words, text with a trailing newline will not end up with two newlines when sent to the MUD.

* If "echo" is true, the command will be echoed in the output window.

* If "queue" is true, the command will be queued (after any other pending commands), otherwise it will be sent immediately

* If "log" is true, the command will be logged to the log file, if one is open, and logging commands is enabled.

* If "history" is true the command will be added to the command history buffer.


name: GetGlobalOptionList
prototype: VARIANT GetGlobalOptionList();
summary: Gets the list of global options
type_of_object: Method
see_also: GetOption SetOption GetAlphaOption SetAlphaOption GetAlphaOptionList GetOptionList GetGlobalOption
python_example: for opt in world.GetGlobalOptionList: world.Note (opt)
doc_name: options
lua_example: for k, v in pairs (GetGlobalOptionList()) do Note (v, " = ", GetGlobalOption(v)) end
description:
Returns a variant array which is a list of all global options that you can get with GetGlobalOption. Global options are client-wide options that are not tied to a particular world. 

The examples show extracting all option names, and their values.

The option names should be reasonably self-explanatory.

vb_example:
For Each opt In world.GetGlobalOptionList
    world.note opt + " = " + cstr (world.GetGlobalOption ( opt ))
Next

java_example:
optionlist = new VBArray(world.GetGlobalOptionList()).toArray();

 for (i = 0; i < optionlist .length; i++)
   world.note(optionlist [i] + " = " + world.GetGlobalOption (optionlist [i] ));

perl_example:
foreach $item (Win32::OLE::in ($world->GetGlobalOptionList))
 {
 $world->note($item . " = " . $world->GetGlobalOption($item));
 }

return_value:
It returns a variant array containing the names of all the options. Use "ubound" to find the number of options in the list. You can then use "GetGlobalOption" to return the value for that particular option.


name: GetGlobalOption
prototype: VARIANT GetGlobalOption(BSTR OptionName);
summary: Gets the value of a global configuration option
vb_example: world.Note world.GetGlobalOption ("DefaultLogFileDirectory")
java_example: /world.Note (world.GetGlobalOption ("DefaultLogFileDirectory"));
perl_example: /$world->Note ($world->GetGlobalOption ("DefaultLogFileDirectory"));
return_value: The value of the requested option, or an "empty" variant if the option does not exist.
type_of_object: Method
see_also: GetGlobalOptionList GetInfo
python_example: world.Note(world.GetGlobalOption ("DefaultLogFileDirectory"))
doc_name: options
lua_example: Note (GetGlobalOption ("DefaultLogFileDirectory"))
description:
Gets the value of an alphanumeric global option. These are global options that are not tied to a particular world.

You can use GetGlobalOptionList to get a list of the names of all possible options.

The option name is not case-sensitive. String option are returned as type BSTR (string), other options (booleans, numbers) are returned as type I4 (long). Non-existant options are returned as type EMPTY (empty).


name: GetPluginAliasOption
prototype: VARIANT GetPluginAliasOption(BSTR PluginID, BSTR AliasName, BSTR OptionName);
summary: Gets the value of a named alias option for a specified plugin
vb_example: Note GetPluginAliasOption("c8efc9f9e1edd118c6f2dbf5", "my_alias", "match")
java_example: Note (GetPluginAliasOption ("c8efc9f9e1edd118c6f2dbf5", "my_alias", "match"));
perl_example: /$world->Note ($world->GetPluginAliasOption ("c8efc9f9e1edd118c6f2dbf5", "my_alias", "match"));
return_value: As described above.
type_of_object: Method
see_also: AddAlias DeleteAlias GetAliasList GetAliasInfo GetPluginAliasList GetAliasOption
python_example: world.Note(world.GetPluginAliasOption ("c8efc9f9e1edd118c6f2dbf5", "my_alias", "match"))
doc_name: aliases
lua_example: Note (GetPluginAliasOption ("c8efc9f9e1edd118c6f2dbf5", "my_alias", "match"))
lua_notes: Lua returns nil where applicable instead of an "empty variant" or "null variant".
description:
Gets the current value of an alias option for the specified plugin.

You must specify a plugin ID, the name of an existing alias, and an alias option from the list given under the description for GetAliasOption. These are the same names as used in the XML world files for alias options.

If you want to find the value of an alias option in the current plugin, use "GetAliasOption".

If you are writing a plugin and want to find "global" MUSHclient alias values, use an empty plugin ID, eg.

  world.Note world.GetPluginAliasOption ("", "my_alias", "enabled")


If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

If the named alias does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the option name is not known, EMPTY is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

See GetAliasOption for a list of option names and values.


name: GetPluginTimerOption
prototype: VARIANT GetPluginTimerOption(BSTR PluginID, BSTR TimerName, BSTR OptionName);
summary: Gets the value of a named timer option for a specified plugin
vb_example: Note GetPluginTimerOption("c8efc9f9e1edd118c6f2dbf5", "my_timer", "enabled")
java_example: Note (GetPluginTimerOption ("c8efc9f9e1edd118c6f2dbf5", "my_timer", "enabled"));
perl_example: /$world->Note ($world->GetPluginTimerOption ("c8efc9f9e1edd118c6f2dbf5", "my_timer", "enabled"));
return_value: As described above.
type_of_object: Method
see_also: AddTimer DeleteTimer GetTimerList GetTimerInfo GetPluginTimerList GetTimerOption
python_example: world.Note(world.GetPluginTimerOption ("c8efc9f9e1edd118c6f2dbf5", "my_timer", "enabled"))
doc_name: timers
lua_example: Note (GetPluginTimerOption ("c8efc9f9e1edd118c6f2dbf5", "my_timer", "enabled"))
lua_notes: Lua returns nil where applicable instead of an "empty variant" or "null variant".
description:
Gets the current value of a timer option for the specified plugin.

You must specify a plugin ID, the name of an existing timer, and a timer option from the list given under the description for GetTimerOption. These are the same names as used in the XML world files for timer options.

If you want to find the value of an timer option in the current plugin, use "GetTimerOption".

If you are writing a plugin and want to find "global" MUSHclient timer values, use an empty plugin ID, eg.

  world.Note world.GetPluginTimerOption ("", "my_timer", "enabled")


If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

If the named timer does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the option name is not known, EMPTY is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).

See GetTimerOption for a list of option names and values.


name: GetPluginTriggerOption
prototype: VARIANT GetPluginTriggerOption(BSTR PluginID, BSTR TriggerName, BSTR OptionName);
summary: Gets the value of a named trigger option for a specified plugin
vb_example: Note GetPluginTriggerOption ("c8efc9f9e1edd118c6f2dbf5", "my_trigger", "enabled")
java_example: Note (GetPluginTriggerOption ("c8efc9f9e1edd118c6f2dbf5", "my_trigger", "enabled"));
return_value: As described above.
type_of_object: Method
see_also: AddTrigger DeleteTrigger GetTriggerList GetTriggerInfo GetPluginTriggerList GetTriggerOption
python_example: world.Note(world.GetPluginTriggerOption ("c8efc9f9e1edd118c6f2dbf5", "my_trigger", "enabled"))
doc_name: timers
lua_example: Note (GetPluginTriggerOption ("c8efc9f9e1edd118c6f2dbf5", "my_trigger", "enabled"))
lua_notes: Lua returns nil where applicable instead of an "empty variant" or "null variant".
description:
Gets the current value of a trigger option for the specified plugin.

You must specify a plugin ID, the name of an existing trigger, and a trigger option from the list given under the description for GetTriggerOption. These are the same names as used in the XML world files for trigger options.

If you want to find the value of an trigger option in the current plugin, use "GetTriggerOption".

If you are writing a plugin and want to find "global" MUSHclient trigger values, use an empty plugin ID, eg.

  world.Note world.GetPluginTriggerOption ("", "my_trigger", "enabled")


If the option name is not known, or is not allowed to be retrieved, a NULL variant is returned.

If the named trigger does not exist, EMPTY is returned. If the name given is invalid, NULL is returned. If the option name is not known, EMPTY is returned. (Use "IsEmpty" and "IsNull" to test for these possibilities).


See GetTriggerOption for a list of option names and values.

perl_example:
/$world->Note ($world->GetPluginTriggerOption ("c8efc9f9e1edd118c6f2dbf5", "my_trigger", "enabled"));


name: AcceleratorTo
prototype: long AcceleratorTo(BSTR Key, BSTR Send, short SendTo);
summary: Add or modify an accelerator key - with "Send To" parameter
type_of_object: Method
see_also: AcceleratorList Accelerator
doc_name: macros
description:
This lets you add or amend the behaviour of MUSHclient "accelerator" keys. For example, you could make Ctrl+E become "eat meat".

This is similar to the Accelerator function (see elsewhere), however this version allows you to specify where the "send text" is to be sent to (for example, to a script, to a speedwalk, to the output window).

These changes only apply to the current world (the one the script function is run in). They override any existing macros or accelerator keys defined for MUSHclient's default behaviour.

You specify three arguments, the keystroke to add or amend, the text to be sent, and where to send it.


The keystroke consists of this syntax:

CTRL + ALT + SHIFT + key

The modifiers CTRL, ALT and SHIFT are all optional, and are not case-sensitive. They can appear in any order. 

The key can be one of the following:

0 1 2 3 4 5 6 7 8 9
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z

Accept Add Apps Attn Backspace Cancel Capital Clear Control Convert Crsel Decimal Delete Divide Down End Enter Ereof Esc Execute Exsel F1 F2 F3 F4 F5 F6 F7 F8 F9 F10 F11 F12 F13 F14 F15 F16 F17 F18 F19 F20 F21 F22 F23 F24 Final Hangeul Hangul Hanja Help Home Insert Junja Kana Kanji LButton LControl LMenu LShift LWin Left MButton Menu ModeChange Multiply NonConvert Noname Numlock Numpad0 Numpad1 Numpad2 Numpad3 Numpad4 Numpad5 Numpad6 Numpad7 Numpad8 Numpad9 Oem_clear Pa1 PageDown PageUp Pause Play Print ProcessKey RButton RControl RMenu RShift RWin Right Scroll Select Separator Snapshot Space Subtract Tab Up Zoom

They are not all guaranteed to work in the way you might expect. These names were obtained from the Windows include files. Some keys may be trapped by the operating system, or not be available on your PC.

Reasonable values to use would be things like:

Alt+Down
Shift+Ctrl+F2
Ctrl+N
PageUp
Ctrl+PageUp
F5
Ctrl+Shift+F9

--------

The "SendTo" argument specifies where the text is to be sent to. It can be one of:

0: World 
1: Command window
2: Output window
3: Status line
4: Notepad (new)
5: Notepad (append)
6: Log File 
7: Notepad (replace)
8: Command queue
9: Send To Variable
10: Execute (re-parse as command)
11: Speedwalk (send text is speedwalk, queue it)
12: Script (send to script engine)
13: Immediate (send to world in front of speedwalk queue)
14: Script - after omit (send to script engine, after lines have been omitted)

The case "set variable" is not very useful because there is no way of specifying which variable to send to.

Use "send to script" if you want to set a variable (using the SetVariable function).

--------

To disable a previously-assigned accelerator, call this function with an empty string as the command. eg

AcceleratorTo ("Ctrl+K", "", 0) -- return to default behaviour

If you wanted to make a key simply "do nothing" then you will need to do something like send an empty script. eg.

AcceleratorTo ("Ctrl+K", "--", 12)  -- execute script with only a comment in it (Lua in this case)

----------

To see the name for a particular keypress use the Input menu -> Key Name dialog. This lets you type a key and have its name displayed. This name can then be used in this function.


Note: If you use AcceleratorTo inside a plugin, that plugin ID is remembered and becomes the current plugin (if possible) when the accelerator is pressed. Thus send-to-script is executed in the calling plugin's script space. If the plugin does not exist when the accelerator is pressed (eg. the plugin has been removed) then the accelerator does nothing. However send-to-execute works whether or not the original plugin still exists, for backwards compatibility with the original Accelerator function.

vb_example:
AcceleratorTo "Ctrl+K", "kill", 0
AcceleratorTo "Ctrl+F", "follow", 0
AcceleratorTo "Ctrl+E", "eat meat", 0
AcceleratorTo "Alt+F2", "Note ""oops""", 12

java_example:
AcceleratorTo ("Ctrl+K", "kill", 0)
AcceleratorTo ("Ctrl+F", "follow", 0)
AcceleratorTo ("Ctrl+E", "eat meat", 0)
AcceleratorTo ("Alt+F2", "4s 3e", 11)  // speedwalk

perl_example:
$world->AcceleratorTo ("Ctrl+K", "kill", 0)
$world->AcceleratorTo ("Ctrl+F", "follow", 0)
$world->AcceleratorTo ("Ctrl+E", "eat meat", 0)
$world->AcceleratorTo ("Alt+F2", "4s 3e", 11)  # speedwalk

return_value:
eBadParameter - the keystroke combination was not accepted
eOptionOutOfRange - the SendTo parameter was out of range
eOK - added OK

lua_example:
AcceleratorTo ("Ctrl+K", "kill", sendto.world)
AcceleratorTo ("Ctrl+F", "follow", sendto.world)
AcceleratorTo ("Ctrl+E", string.rep ('-', 60), sendto.output)  -- 60 hyphens in output window

-- execute a script
AcceleratorTo ("Ctrl+M", "DoCommand 'preferences' ", sendto.script)  -- send to script

AcceleratorTo ("Ctrl+E", "") -- revert to original behaviour for Ctrl+E

lua_notes:
The "SendTo" field can be specified using the "sendto" table in the Lua global address space, as follows:

sendto.world = 0
sendto.command = 1
sendto.output = 2
sendto.status = 3
sendto.notepad = 4
sendto.notepadappend = 5
sendto.logfile = 6
sendto.notepadreplace = 7
sendto.commandqueue = 8
sendto.variable = 9
sendto.execute = 10
sendto.speedwalk = 11
sendto.script = 12
sendto.immediate = 13
sendto.scriptafteromit = 14


name: PlaySound
prototype: long PlaySound(short Buffer, BSTR FileName, BOOL Loop, double Volume, double Pan);
summary: Plays a sound using DirectSound
type_of_object: Method
see_also: Sound StopSound GetSoundStatus
doc_name: utils
description:
Plays a sound, or adjusts the parameters of a sound that is currently playing. 

Also see below in the Lua notes for PlaySoundMemory which plays a sound loaded into memory.

You can choose to use 1 of 10 "sound buffers" - sounds placed in different buffers will play simultaneously.

If a sound is currently playing in the selected buffer it is automatically stopped and its memory freed. Thus you do not need to stop sounds first before replacing them by something else.

See: http://mushclient.com/forum/?id=8721 for a more detailed description.

You can use StopSound to stop the sound playing at any time, and GetSoundStatus to see if a sound is playing or not in a particular buffer.

------------
Buffer: Which buffer to use (1 to 10) or 0 to take the first free buffer when playing a new sound. If there are no free buffers, buffer 1 is chosen.

------------
FileName: The sound file to play. Can be the empty string in which case you are modifying the behaviour of a currently-playing sound in that buffer.

If the file name is a fully-qualified path name (ie. it starts with a slash, or a drive letter, colon, slash like "C:/") then it is used "as is".

Otherwise, MUSHclient prepends the MUSHclient execution directory + "sounds" subdirectory to the name

For example, the file name "swordhit.wav" would be looked for at: C:/Program Files/MUSHclient/sounds/swordhit.wav

You can use forward slashes in the file name (for convenience in typing strings in scripts), they are converted to backslashes.

The only file type supported is a .wav file, as follows:

* 16-bit
* 22.05 KHz
* PCM (ie. uncompressed)
* Mono or Stereo

Note that the entire file is read into memory, uncompressed. We do not attempt to "stream" the file. Thus large sound files will take a lot of memory. The sound functions are intended for sound effects and short loops of music or ambient sounds. They are not intended to play Beethoven's Fifth Symphony while you play.

You can convert sound files which are in other formats (eg. MP3) into WAV files by using various programs. One very good free program is Audacity, which is available for Mac or Windows:

http://audacity.sourceforge.net/

In Audacity, open your file, and then choose: File Menu -> Export As WAV...

------------
Loop: true or false (1 or 0). If true the sound loops, and thus repeats indefinitely until cancelled. A sound can be cancelled by calling the StopSound function for that buffer number, or simply playing a different sound in that buffer. Obviously it is preferable to not use buffer 0 if you are planning to loop, because you won't know which buffer actually got allocated.

If omitted in Lua scripting this defaults to false (not looping).

------------
Volume: -100 to 0. This is the number of db (decibels) to attenuate (reduce) the sound. Decibels are a logarithmic scale, every 3 db corresponds to half the perceived sound volume. Thus a volume of zero is "full volume". A volume of -3 is half-volume, -6 is quarter-volume, and so on. If you want to fade a sound away rather than just cut if off, you get quite a good effect by readjusting the sound every half second or so in a loop, reducing the volume by -2 each time, from 0 to -40. A sound at volume -40 is pretty quiet, after which you can just stop playing the sound. If you are going to write a "reduce the volume" loop you would need to use Lua coroutines, or some other timer mechanism, to turn the volume in that channel down periodically.

If omitted in Lua scripting this defaults to 0 (full volume).

If the volume is out of the range -100 to 0 then 0 (full volume) is used.

------------
Pan: -100 to +100. This is the number of db (decibels) to attenuate the sound in one speaker, to create a stereo affect (that is, more from one speaker than the other). 

Pan of -100 makes the sound come completely from the left speaker (the right speaker is cut off).
Pan of 0 makes the sound come from both speakers, and thus it sounds centered.
Pan of +100 makes the sound come completely from the right speaker (the left speaker is cut off).

If omitted in Lua scripting this defaults to 0 (both speakers, or centered).

If the pan value is out of the range -100 to +100 then 0 is used.


-----------

Playing sounds in the background ...

The default behaviour is for the sounds to be only played if MUSHclient is currently active (the foreground window, that is). If you switch to another application the sound will cut out (and resume if it is still playing when you switch back).

To have the sound play regardless, you need to set a world configuration option, like this:

SetOption ("play_sounds_in_background", 1)  

That option only needs to be set once per world file. Once the world file is saved to disk the option will persist.

vb_example:
' play sound once only, full volume, centered, in buffer 1
PlaySound 1, "boing.wav", vbFalse, 0, 0

' play sound once only, quarter volume, from the left speaker, in buffer 2
PlaySound 2, "ding.wav", vbFalse, -6, -100

' play sound looping, eighth volume, from the right speaker, in buffer 3
PlaySound 3, "forest.wav", vbTrue, -9, 100 

' play sound once only, full volume, slightly to the left, in the first available buffer
PlaySound 0, "swordhit.wav", vbFalse, 0, -3  


'  To adjust an existing sound, like the forest sound above:

PlaySound 3, "", vbFalse, -9, 100  ' cancel looping for buffer 3, still play at -9 db
PlaySound 3, "", vbFalse, -12, 100 ' cancel looping for buffer 3 and make softer

return_value:
eCannotPlaySound:

* DirectSound not initialized
* An attempt made to change the volume, looping, or pan of a sound that is not playing
* Sound file is not a .wav file
* Cannot parse sound file
* Sound file is not a PCM format file (wrong sound file format)
* Cannot find sound data in sound file
* Cannot create internal sound buffer (maybe all in use)
* Cannot read sound data into memory
* DirectSound refuses to play the sound

eBadParameter:

* An attempt made to change the volume, looping, or pan of a sound that is not in use
* No sound file name given, and buffer 0 given
* Buffer number outside range 0 to 10
* File name > 127 characters long

eFileNotFound:

* Sound file not found

eOK:

* Sound played OK (or volume/looping/pan adjusted OK)

lua_example:
-- play sound once only, full volume, centered, in buffer 1
PlaySound (1, "boing.wav", false, 0, 0)  

-- play sound once only, quarter volume, from the left speaker, in buffer 2
PlaySound (2, "ding.wav", false, -6, -100)  

-- play sound looping, eighth volume, from the right speaker, in buffer 3
PlaySound (3, "forest.wav", true, -9, 100) 

-- play sound once only, full volume, slightly to the left, in the first available buffer
PlaySound (0, "swordhit.wav", false, 0, -3)  


To adjust an existing sound, like the forest sound above:

PlaySound (3, "", false, -9, 100)  --> cancel looping for buffer 3, still play at -9 db
PlaySound (3, "", false, -12, 100)  --> cancel looping for buffer 3 and make softer


To wait until a previous sound has finished playing:


require "wait"

function PlayOneSound (name)
  wait.make ( function ()
    while GetSoundStatus (1) > 0 do
      wait.time (0.1)
    end -- while previous sound still playing
    PlaySound (1, name)
  end )  -- end of wait.make
end -- PlayOneSound 

PlayOneSound ("1.wav")
PlayOneSound ("2.wav")
PlayOneSound ("3.wav")

lua_notes:
All arguments except the buffer number are optional.

The file name defaults to the empty string, looping defaults to false, volume defaults to full volume, and panning defaults to centered.

From version 4.42 onwards, Lua also supports PlaySoundMemory which plays a sound file loaded into a memory buffer.

In this case the second argument is the memory buffer, not the file name.

local f = assert (io.open ("some_sound.wav", "rb"))
local sound_data = f:read ("*a")  -- read all of it
f:close ()  -- close it

PlaySoundMemory (1, sound_data, false, 0, 0)  -- play sound loaded into sound_data


name: StopSound
prototype: long StopSound(short Buffer);
summary: Stop playing a sound started by PlaySound
vb_example: StopSound 0 ' Stop playing all sounds StopSound 1 ' Stop playing sound buffer #1
return_value: eBadParameter: Buffer number outside range 0 to 10 eOK: Requested buffer(s) have been stopped.
type_of_object: Method
see_also: Sound PlaySound GetSoundStatus
doc_name: utils
lua_example: StopSound (0) -- Stop playing all sounds StopSound (1) -- Stop playing sound buffer #1
lua_notes: The buffer number is optional and defaults to zero, which will stop all sounds from playing.
description:
Stops one, or all, sound buffers from playing. 

It is not necessary to call this for non-looping sounds, which stop of their own accord anyway, however doing so would free up the memory used by the sound.

The buffer argument specifies which buffer to stop (1 to 10) or 0 to stop all sound buffers playing.


name: GetSoundStatus
prototype: long GetSoundStatus(short Buffer);
summary: Gets the status of a sound started by PlaySound
vb_example: result = GetSoundStatus (1) ' find what sound buffer 1 is doing
type_of_object: Method
see_also: Sound PlaySound StopSound
doc_name: utils
lua_example: result = GetSoundStatus (1)
description:
Gets the status of one of the sound buffers.

If you started playing a sound with StartSound this will tell you if it is still playing, and if so, whether it is set to loop or not.

Basically if the returned number is > 0 then the sound is playing, and if it is <= 0 then it is not playing.

You might test this in a timer to see if a sound had stopped playing (eg. some music), and if so, play something else.

Buffer: Which buffer to query (1 to 10).

return_value:
-3: Sound system is not initialized (ie. DirectX not installed or too early version)
-2: That buffer is free (never played a sound, or the sound was stopped with StopSound)
-1: Requested buffer number out of range 1 to 10
 0: That buffer has reached the end and stopped playing 
 1: That buffer is playing a sound, but not looping
 2: That buffer is playing a sound, which is a looping sound


name: SetCommandWindowHeight
prototype: long SetCommandWindowHeight(short Height);
summary: Set the height of the command (input) window
description: Sets the height of the command window in pixels.
vb_example: SetCommandWindowHeight 15 ' enough for a line SetCommandWindowHeight 0 ' not visible
java_example: SetCommandWindowHeight (15) // enough for a line SetCommandWindowHeight (0) // not visible
type_of_object: Method
lua_example: SetCommandWindowHeight (15) -- enough for a line SetCommandWindowHeight (0) -- not visible
return_value:
eBadParameter: Specified height is < 0 or such that the output window would be < 20 pixels high.
eOK: Completed OK

see_also:
MoveMainWindow MoveNotepadWindow GetMainWindowPosition GetWorldWindowPosition GetNotepadWindowPosition MoveWorldWindowX SetWorldWindowStatus MoveWorldWindow


name: SetToolBarPosition
prototype: long SetToolBarPosition(short Which, BOOL Float, short Side, long Top, long Left);
summary: Sets the position of the game toolbars on the screen.
return_value: eBadParameter: A parameter was of range. eOK: Successfully completed
type_of_object: Method
doc_name: utils
description:
Moves the toolbars around to your liking. The intention is to allow newly-distributed copies of MUSHclient to configure themselves appropriately.

Which: which toolbar, as follows:

1: Main toolbar (with the New, Open, Save, Print icons).
2: Game toolbar (with buttons for Edit Trigger, Edit Alias, log, etc.)
3: Activity toolbar (which shows the numbers 1 to 10)
4: Info toolbar (which lets you display informational messages)

Float: true or false

If true, the toolbar floats as a small independent window.
If false, the toolbar is docked to one side of the main client frame window

Side: which side to dock to, as follows:

1: top side
2: bottom side
3: left side
4: right side

If the style is set to "Float" then only "top" or "left" are valid (1 or 3), in which case the floating window has its icons arranged vertically or horizontally.

Top: Y co-ordinate of the top-left corner of the toolbar in client co-ordinates
Left: X co-ordinate of the top-left corner of the toolbar in client co-ordinates

(eg. 0, 0 would be the top-left corner).

Sizes of toolbars are:

1: 26 pixels high, 265 wide
2: 26 pixels high, 478 wide
3: 26 pixels high, 234 wide
4: 21 pixels high, 1007 wide

To place them side-by-side, you need to allow room for each one. For example:

SetToolBarPosition (1, false, 1, 0, 0)    -- main toolbar
SetToolBarPosition (2, false, 1, 0, 264)  -- game toolbar next to it
SetToolBarPosition (3, true, 1, 30, 500)  -- float activity toolbar

vb_example:
SetToolBarPosition 1, false, 1, 0, 0    ' main toolbar
SetToolBarPosition 2, false, 1, 0, 264  ' game toolbar next to it
SetToolBarPosition 3, true, 1, 30, 500  ' float activity toolbar

see_also:
MoveMainWindow MoveWorldWindow MoveNotepadWindow GetMainWindowPosition GetWorldWindowPosition GetNotepadWindowPosition SetCommandWindowHeight

lua_example:
SetToolBarPosition (1, false, 1, 0, 0)    -- main toolbar
SetToolBarPosition (2, false, 1, 0, 264)  -- game toolbar next to it
SetToolBarPosition (3, true, 1, 30, 500)  -- float activity toolbar


name: ShiftTabCompleteItem
prototype: long ShiftTabCompleteItem(BSTR Item);
summary: Adds an item to the list shown for Shift+Tab completion
type_of_object: Method
doc_name: utils
description:
Lets you add an item to the menu that pops up when you type a partial word and hit Shift+Tab in the command window.

The default is, if you type a partial script function name and hit Shift+Tab it will complete the function, as an aid to writing scripts, eg.

col<Shift+Tab> suggests ColourNameToRGB, ColourNote and ColourTell.

Now you can add items of your own to the list (for example, Python functions).

To do this, use this function for each additional word.

For example:

ShiftTabCompleteItem ("repeat")
ShiftTabCompleteItem ("until")
ShiftTabCompleteItem ("while")

You should use the correct capitalization that you want in the finished word.

Words must start with a letter, and then be alphanumeric (A-Z, a-z, 0-9) plus period, underscore, hyphen.

You can use three special words for additional control:

ShiftTabCompleteItem ("<clear>")   --> clears the list of user-added items
ShiftTabCompleteItem ("<nofunctions>")  -->  suppresses the completion of script function names (like ColourTell)
ShiftTabCompleteItem ("<functions>")  --> allows the completion of script function names 

These items are not saved in the world file, they should be loaded each time.

You might use the "<nofunctions>" action if you were simply planning to play the MUD, and didn't want script functions popping up in the menu.

vb_example:
ShiftTabCompleteItem "Function"
ShiftTabCompleteItem "While"
ShiftTabCompleteItem "vbTrue"
ShiftTabCompleteItem "vbFalse"

return_value:
eBadParameter: Empty string supplied, string > 30 characters, or string contains invalid characters
eOK: Added OK

lua_example:
ShiftTabCompleteItem ("repeat")
ShiftTabCompleteItem ("until")
ShiftTabCompleteItem ("while")


-- special strings

ShiftTabCompleteItem ("<clear>")   --> clears the list of user-added items
ShiftTabCompleteItem ("<nofunctions>")  -->  suppresses the completion of script function names (like ColourTell)
ShiftTabCompleteItem ("<functions>")  --> allows the completion of script function names


name: NotepadReadOnly
prototype: long NotepadReadOnly(BSTR Title, BOOL ReadOnly);
summary: Make a selected notepad window read-only
vb_example: NotepadReadOnly "test", vbTrue
java_example: NotepadReadOnly ("test", true);
return_value: 0 = Could not do it (eg. that notepad does not exist) 1 = Changed status OK.
type_of_object: Method
see_also: GetNotepadWindowPosition NotepadColour GetNotepadList NotepadFont
doc_name: notepad
lua_example: NotepadReadOnly ("test", true)
lua_notes: The ReadOnly argument is optional and defaults to true.
description:
This lets you mark a notepad window as read-only.

This might be useful for help screens or other "output-only" information.

You can specify true or false as the second argument. Under Lua, it defaults to true.


name: AddFont
prototype: long AddFont(BSTR PathName);
summary: Adds a custom font for use by MUSHclient
vb_example: AddFont "myextrafont.ttf"
type_of_object: Method
doc_name: utils
lua_example: AddFont ("myextrafont.ttf")
description:
This adds a font (specified by pathname) into the MUSHclient application space. It can then be used by world windows for output or command window fonts.

Any number of extra fonts can be added per world. (This feature added in version 4.93 of MUSHclient. Prior to version 4.93 you could only add one extra font at a time).

The intention here is for specialized fonts (like mapping fonts) to be made available without having to add extra font files to the Windows directory.

This is only supported on Windows 2000 or later (eg. Windows XP, Vista). It is not supported under Windows 95/98/ME. Use GetInfo (265) through to GetInfo (268) to find which version of Windows you are running under. (Basically GetInfo (265) needs to return 5 or higher).


The file name can specify any of the following files.

.fon	Font resource file.
.fnt	Raw bitmap font file.
.ttf	Raw TrueType file.
.ttc	East Asian Windows: TrueType font collection.
.fot	TrueType resource file.
.otf	PostScript OpenType font.

.mmm	multiple master Type1 font resource file. 

It must be used with .pfm and .pfb files.

.pfb	Type 1 font bits file. 

It is used with a .pfm file.

.pfm	Type 1 font metrics file. 

It is used with a .pfb file.

To add a font whose information comes from several resource files, point lpszFileName to a string with the file names separated by a | --for example, abcxxxxx.pfm | abcxxxxx.pfb.

return_value:
eBadParameter - empty file name given
eNoSuchCommand - not supported on your version of Windows
eFileNotFound - file not found, or Windows rejected it as a font file
eOK - added OK


name: WindowAddHotspot
summary: Adds a hotspot to a miniwindow
type_of_object: Method
doc_name: miniwindows
prototype:
long WindowAddHotspot(BSTR WindowName, BSTR HotspotId, long Left, long Top, long Right, long Bottom, BSTR MouseOver, BSTR CancelMouseOver, BSTR MouseDown, BSTR CancelMouseDown, BSTR MouseUp, BSTR TooltipText, long Cursor, long Flags);

description:
Each miniwindow can have any number of hotspots (including zero). Each one designates a rectangle which has some significance if you mouse over it, or click inside it. You should take care not to overlap hotspot rectangles or they may not behave as you expect. When checking for mouse clicks, hotspots are evaluated in ascending alphabetic order by hotspot id.

Hotspots are not, in themselves, visible graphic elements. You would normally associate them with a piece of text (for a hyperlink) or a graphical element such as a button or checkbox. For example, when drawing text, you know the starting point of the text, the height of the text, and the width of the text. This can be used to create a hotspot over the same place the text appeared.

Most of the functionality of hotspots is provided by script "callbacks" - that is, when you mouse over a hotspot, a function in your main script file, or plugin, is called (if you nominate one). 

NOTE: Hotspot functions must be visible to MUSHclient when querying the script engine. Thus functions declared as "local" in Lua (or something similar in other languages) will not work.

WARNING: If you set the "draw underneath" flag when calling WindowCreate, then you cannot use hotspots, as the hotspots are underneath the text and will not be detected.

WARNING: If you set the "ignore mouse" flag when calling WindowCreate, then you cannot use hotspots, as mouse clicks and movement will not be detected.

If you want to handle dragging (moving the mouse after clicking), see also WindowDragHandler.

For more information, see:

 http://www.gammon.com.au/mushclient/mw_hotspots.htm

This create a hotspot in the miniwindow, and remembers it by the nominated "hotspot id".

WindowName - the name of an existing miniwindow. Names are case-sensitive.

HotspotId - the hotspot id to be associated with this particular hotspot. Hotspot IDs are case-sensitive.

Left, Top, Right, Bottom - describes the hotspot rectangle.

MouseOver - the name of the script function to be called when you mouse over the hotspot rectangle

CancelMouseOver - the name of the script function to be called when you move the mouse away from the hotspot rectangle

MouseDown - the name of the script function to be called when you mouse down in the hotspot rectangle

CancelMouseDown - the name of the script function to be called when you release the mouse not in the hotspot rectangle that the mouse-down occurred in

MouseUp - the name of the script function to be called when you release the mouse in the hotspot rectangle that the mouse-down occurred in

TooltipText - the text here is shown automatically if you "hover" the mouse over the hotspot for about a second. It is then removed after a few seconds. This is intended for help messages (maximum 999 characters). If there is a tab character (0x09) in the tooltip text, the text before the tab is considered the tooltip title (shown in bold on a separate line), and the rest of the text is the non-bold tooltip text.

To change a tooltip later, see: WindowHotspotTooltip

Cursor - a number which indicates what shape the mouse pointer is to take when over the hotspot, as follows:

-1: no cursor

0: arrow
1: hand
2: I-beam
3: + symbol
4: wait (hour-glass)
5: up arrow
6: arrow nw-se
7: arrow ne-sw
8: arrow e-w
9: arrow n-s
10: arrow - all ways
11: (X) cannot do action
12: help (? symbol)

Flags - flags to modify hotspot behaviour. These should be or'd together.

0x01 : All mouse-over events are reported to the mouseover callback (if any)

For subsequent mouse-overs within a single hotspot the flags will have the 0x80 bit set. For the first mouse-over the 0x80 bit will be clear.


The callback functions should look like this:


function mouseover (flags, hotspot_id)
  Note ("we moused over hotspot " .. hotspot_id)
  return 0  -- needed for some languages
end -- mouseover

Since the hotspot ID is passed to the callback function, you can share the same function amongst all your hotspots. For example, a "mouse down" function could handle all the hyperlinks in a miniwindow - by using the hotspot ID, it could look up in a table what action to perform for this particular hotspot.

The function return code is ignored, however for some languages, like PHP, you should return 0, otherwise you will get a runtime error.

The flags parameter is a bit mask as follows:

0x01 - Shift key down
0x02 - Control key down
0x04 - Alt key down
0x10 - LH mouse
0x20 - RH mouse
0x40 - double-click
0x80 - mouse-over not first time
0x100 - scroll wheel scrolled (towards you)
0x200 - middle mouse

So, for example, if the left-hand mouse was double-clicked whilst the shift and control keys were held down, the flags would be:


flags = 0x01 + 0x02 + 0x10 + 0x40   --> namely 0x53 (83 in decimal)

You could test this in Lua like this:

if bit.band (flags, 0x20) ~= 0 then
  -- mouse be RH mouse
end -- if


WARNING: The hotspot callbacks are not functions, but names of functions. That is, they should be supplied as string arguments. The supplied names are looked up in the script space at the appropriate time.

WARNING: The hotspot callbacks have to be in the same script space as each other (either all in the same plugin, or the world script file).

return_value:
eNoSuchWindow - no such miniwindow
eInvalidObjectLabel - one of the script functions is not a valid function name
eHotspotPluginChanged - the plugin is not the same one as used before for hotspots
eItemInUse - attempt to add a hotspot in the middle of adding a hotspot
eOK - completed OK

see_also:
WindowDeleteAllHotspots WindowDeleteHotspot WindowHotspotInfo WindowHotspotList WindowCreate WindowDragHandler WindowHotspotTooltip WindowMoveHotspot

lua_example:
WindowAddHotspot(win, "hs1",  
                 10, 10, 60, 20,   -- rectangle
                 "mouseover", 
                 "cancelmouseover", 
                 "mousedown",
                 "cancelmousedown", 
                 "mouseup", 
                 "Click here to be healed",  -- tooltip text
                 miniwin.cursor_hand,        -- hand cursor
                 0)                          -- flags

lua_notes:
The handler function names can be omitted and default to the empty string (ie. no function).
The Cursor and Flags arguments are optional and default to zero.

You can use the following constants for the cursor:

miniwin.cursor_none = -1
miniwin.cursor_arrow = 0
miniwin.cursor_hand = 1
miniwin.cursor_ibeam = 2
miniwin.cursor_plus = 3
miniwin.cursor_wait = 4
miniwin.cursor_up = 5
miniwin.cursor_nw_se_arrow = 6
miniwin.cursor_ne_sw_arrow = 7
miniwin.cursor_ew_arrow = 8
miniwin.cursor_ns_arrow = 9
miniwin.cursor_both_arrow = 10
miniwin.cursor_x = 11
miniwin.cursor_help = 12


You can use the following constants for the flags:

miniwin.hotspot_report_all_mouseovers = 1


In the callback functions (called on mousedown etc.) you can use the following constants for the flags (first argument to the callback):

miniwin.hotspot_got_shift = 1
miniwin.hotspot_got_control = 2
miniwin.hotspot_got_alt = 4
miniwin.hotspot_got_lh_mouse = 16
miniwin.hotspot_got_rh_mouse = 32
miniwin.hotspot_got_dbl_click = 64
miniwin.hotspot_got_not_first = 128
miniwin.hotspot_got_middle_mouse = 512

miniwin.wheel_got_shift = 1         
miniwin.wheel_got_control = 2
miniwin.wheel_got_alt = 4
miniwin.wheel_scroll_back = 256


name: WindowDeleteAllHotspots
prototype: long WindowDeleteAllHotspots(BSTR WindowName);
summary: Deletes all hotspots from a miniwindow
return_value: eNoSuchWindow - no such miniwindow eOK - completed OK
type_of_object: Method
see_also: WindowAddHotspot WindowDeleteHotspot WindowHotspotInfo WindowHotspotList WindowCreate
doc_name: miniwindows
lua_example: WindowDeleteAllHotspots (win);
description:
This deletes all hotspots from the miniwindow.

WindowName - the name of an existing miniwindow.

For more information, see:

 http://www.gammon.com.au/mushclient/mw_hotspots.htm


name: WindowDeleteHotspot
prototype: long WindowDeleteHotspot(BSTR WindowName, BSTR HotspotId);
summary: Deletes a hotspot from a miniwindow
return_value: eNoSuchWindow - no such miniwindow eHotspotNotInstalled - no such hotspot eOK - completed OK
type_of_object: Method
see_also: WindowAddHotspot WindowDeleteAllHotspots WindowHotspotInfo WindowHotspotList WindowCreate
doc_name: miniwindows
lua_example: WindowDeleteHotspot (win, "hs1");
description:
This deletes the hotspot from the miniwindow.

WindowName - the name of an existing miniwindow.

HotspotId - the hotspot id to be deleted.

For more information, see:

 http://www.gammon.com.au/mushclient/mw_hotspots.htm


name: WindowHotspotInfo
prototype: VARIANT WindowHotspotInfo(BSTR WindowName, BSTR HotspotId, long InfoType);
summary: Returns information about a hotspot
type_of_object: Method
see_also: WindowAddHotspot WindowDeleteHotspot WindowDeleteAllHotspots WindowHotspotList WindowCreate
doc_name: miniwindows
lua_example: WindowHotspotInfo(win, "hs1", 5)
lua_notes: Lua returns nil instead of a NULL or EMPTY variant.
description:
This returns information about a hotspot. You need to specify the name of the miniwindow, and the hotspot id you used when creating the hotspot.

WindowName - the name of an existing miniwindow.

HotspotId - the hotspot id you used when you created the hotspot.

InfoType - the information you want:

1: Rectangle: Left
2: Rectangle: Top
3: Rectangle: Right
4: Rectangle: Bottom
5: MouseOver function name
6: CancelMouseOver function name
7: MouseDown function name
8: CancelMouseDown function name
9: MouseUp function name
10: TooltipText
11: Cursor
12: Flags
13: MoveCallback function name  (from DragHandler call)
14: ReleaseCallback function name (from DragHandler call)
15: DragHandler flags (from DragHandler call)



For more information, see:

 http://www.gammon.com.au/mushclient/mw_hotspots.htm

return_value:
The specified information about the hotspot, as described above.
An EMPTY variant, if the hotspot does not exist.
A NULL variant if the InfoType is not a valid type.


name: WindowFontInfo
prototype: VARIANT WindowFontInfo(BSTR WindowName, BSTR FontId, long InfoType);
summary: Returns information about a font
type_of_object: Method
see_also: WindowCreate WindowFont WindowFontList WindowText WindowTextWidth
doc_name: miniwindows
lua_example: WindowFontInfo (win, "f", 1) --> get text height
lua_notes: Lua returns nil instead of a NULL or EMPTY variant.
description:
This returns information about a loaded font. You need to specify the name of the miniwindow, and the font id you used when loading the font.

Probably the most important item is number 1 - the height of the font. If you are drawing multiple lines of a particular font, you should add the font height to the "y" parameter of the rectangle, to move the pixel position down the window an appropriate amount.

WindowName - the name of an existing miniwindow.

FontId - the font id you used when you loaded the font.

InfoType - the information you want:

1: Height - Specifies the height (ascent + descent) of characters.

2: Ascent - Specifies the ascent (units above the base line) of characters

3: Descent - Specifies the descent (units below the base line) of characters.

4: Internal Leading - Specifies the amount of leading (space) inside the bounds set by the height. Accent marks and other diacritical characters may occur in this area. The designer may set this to zero.

5: External Leading - Specifies the amount of extra leading (space) that the application adds between rows. Since this area is outside the font, it contains no marks and is not altered by text output calls. The designer may set this member to zero.

6: Average Character Width - Specifies the average width of characters in the font (generally defined as the width of the letter x). This value does not include the overhang required for bold or italic characters.

7: Maximum Character Width - Specifies the width of the widest character in the font.

8: Weight - Specifies the weight of the font.

9: Overhang - Specifies the extra width per string that may be added to some synthesized fonts. When synthesizing some attributes, such as bold or italic, graphics device interface (GDI) or a device may have to add width to a string on both a per-character and per-string basis. For example, GDI makes a string bold by expanding the spacing of each character and overstriking by an offset value; it italicizes a font by shearing the string. In either case, there is an overhang past the basic string. For bold strings, the overhang is the distance by which the overstrike is offset. For italic strings, the overhang is the amount the top of the font is sheared past the bottom of the font.

10: Digitized Aspect X	- Specifies the horizontal aspect of the device for which the font was designed.

11: Digitized Aspect Y	 - Specifies the vertical aspect of the device for which the font was designed. The ratio of the DigitizedAspectX and DigitizedAspectY is the aspect ratio of the device for which the font was designed.

12: First Character - Specifies the value of the first character defined in the font.

13: Last Character - Specifies the value of the last character defined in the font

14: Default Character - Specifies the value of the character to be substituted for characters not in the font.

15: Break Character - Specifies the value of the character that will be used to define word breaks for text justification.

16: Italic - Specifies an italic font if it is nonzero.

17: Underlined - Specifies an underlined font if it is nonzero.

18: Struck Out - Specifies a strikeout font if it is nonzero.

19: Pitch And Family - Specifies information about the pitch, the technology, and the family of a physical font.

20: Character Set - Specifies the character set of the font.

21: Name - Specifies the name of the font


For more information, see:

http://www.gammon.com.au/mushclient/mw_text.htm

return_value:
The specified information about the font, as described above.
An EMPTY variant, if the font does not exist.
A NULL variant if the InfoType is not a valid type.


name: WindowImageInfo
prototype: VARIANT WindowImageInfo(BSTR WindowName, BSTR ImageId, long InfoType);
summary: Returns information about an image
type_of_object: Method
see_also: WindowCreate WindowCreateImage WindowDrawImage WindowImageList WindowImageOp WindowLoadImage
doc_name: miniwindows
lua_example: WindowImageInfo(win, "im1", 6)
lua_notes: Lua returns nil instead of a NULL or EMPTY variant.
description:
This returns information about a loaded image. You need to specify the name of the miniwindow, and the image id you used when loading the image.

WindowName - the name of an existing miniwindow.

ImageId - the image id you used when you loaded the image.

InfoType - the information you want:

1: Type - Specifies the bitmap type.

2: Width - Specifies the width, in pixels, of the bitmap.

3: Height - Specifies the height, in pixels, of the bitmap.

4: WidthBytes - Specifies the number of bytes in each scan line.

5: Planes - Specifies the count of color planes.

6: BitsPixel - Specifies the number of bits required to indicate the color of a pixel.

For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

return_value:
The specified information about the image, as described above.
An EMPTY variant, if the image does not exist.
A NULL variant if the InfoType is not a valid type.


name: WindowInfo
prototype: VARIANT WindowInfo(BSTR WindowName, long InfoType);
summary: Returns information about a miniwindow
type_of_object: Method
see_also: WindowCreate WindowList WindowShow
doc_name: miniwindows
lua_example: WindowInfo (win, 4) --> get height
lua_notes: Lua returns nil instead of a NULL or EMPTY variant.
description:
This returns information about a particular miniwindow. You might use this to find where the window is on the screen, what its size is, whether it is visible, and so on.

WindowName - the name of an existing miniwindow.

InfoType - the information you want:

1: Left (from WindowCreate)

2: Top (from WindowCreate)

3: Width

4: Height

5: Show flag

6: Is it hidden right now?

7: Layout position code

8: Flags

9: Background colour

10: Where it is right now: left

11: Where it is right now: top

12: Where it is right now: right

13: Where it is right now: bottom

14: Where mouse last was (mouse down, mouse up or move) - X position - relative to miniwindow

15: Where mouse last was (mouse down, mouse up or move) - Y position - relative to miniwindow

16: Incremented each time items 14/15 are updated.

17: Where mouse was (during drag operation) - X position - relative to output window

18: Where mouse was (during drag operation) - y position - relative to output window

19: Hotspot ID of the hotspot currently being moused-over (empty string if none)

20: Hotspot ID of the hotspot currently being moused-down in (empty string if none)

21: Date/time the miniwindow was installed.

22: The Z-Order of the miniwindow.

23: The Plugin ID of the plugin that created this miniwindow (empty string if no plugin)


InfoType 10 to 13 are where the auto positioning last placed the window (the last time the main screen was refreshed).

The "show" flag is whether you want the window shown. Infotype 6 is whether it had to be temporarily hidden. This only applies to position codes 5, 7, 9, 11. The window will thus be visible if:

* The Show flag is true (Infotype 5)

* The "Is it hidden right now" flag is false (Infotype 6)

* It is actually positioned somewhere it can be seen

* Another window is not on top of it


The mouse position (info items 14 and 15) are updated each time a mouse-down, mouse-up, or mouse-move event is processed by a miniwindow. When this happens, item 16 is incremented. This will eventually "wrap around" and become negative once it is incremented 2,147,483,648 times.

The intention here is that if item 16 changes (whether up or down) then you know a new mouse coordinate has been recorded for this miniwindow.

The mouse position  (for info items 14 and 15) is relative to the start of the miniwindow, whatever that is. You could use this to create a pop-up menu at the point at which the mouse was clicked.

If item 20 is not the empty string, then the mouse is currently "captured" by the nominated hotspot.

For more information, see:

http://www.gammon.com.au/mushclient/mw_creation.htm

return_value:
The specified information about the window, as described above.
An EMPTY variant, if the window does not exist.
A NULL variant if the InfoType is not a valid type.


name: WindowList
prototype: VARIANT WindowList();
summary: Lists all miniwindows
type_of_object: Method
see_also: WindowCreate WindowInfo WindowShow
doc_name: miniwindows
lua_notes: Lua returns nil if there are no miniwindows.
description:
This returns a list of all miniwindows created for this world. You could use this to find which windows have been created, and then use WindowInfo to find information about each one.

For more information, see:

http://www.gammon.com.au/mushclient/mw_creation.htm

return_value:
If there are no miniwindows then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the miniwindows. Use "ubound" to find the number of miniwindows in the list. You can then use "WindowInfo" to find details about each miniwindow.

lua_example:
-- show all windows
windows = WindowList()

if windows then
  for _, v in ipairs (windows) do 
    Note (v) 
  end
end -- if any


name: WindowFontList
prototype: VARIANT WindowFontList(BSTR WindowName);
summary: Lists all fonts loaded into a miniwindow
type_of_object: Method
see_also: WindowCreate WindowFont WindowFontInfo WindowText WindowTextWidth
doc_name: miniwindows
lua_notes: Lua returns nil if there are no fonts.
description:
This returns a list of all fonts loaded into this miniwindow. You could use this to find which fonts have been loaded, and then use WindowFontInfo to find information about each one.

WindowName - the name of the miniwindow to check for fonts.


For more information, see:

http://www.gammon.com.au/mushclient/mw_text.htm

return_value:
If there are no fonts loaded then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the font ids of all the fonts. Use "ubound" to find the number of fonts in the list. You can then use "WindowFontInfo" to find details about each fonts.

lua_example:
-- show all fonts
fonts = WindowFontList(win)

if fonts then
  for _, v in ipairs (fonts) do 
    Note (v) 
  end
end -- if any


name: WindowHotspotList
prototype: VARIANT WindowHotspotList(BSTR WindowName);
summary: Lists all hotspots installed into a miniwindow
type_of_object: Method
see_also: WindowCreate WindowAddHotspot WindowDeleteAllHotspots WindowDeleteHotspot WindowHotspotList
doc_name: miniwindows
lua_notes: Lua returns nil if there are no hotspots.
description:
This returns a list of all hotspots loaded into this miniwindow. You could use this to find which hotspots have been created, and then use WindowHotspotInfo to find information about each one.

WindowName - the name of the miniwindow to check for hotspots.


For more information, see:

http://www.gammon.com.au/mushclient/mw_hotspots.htm

return_value:
If there are no hotspots installed then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the hotspot ids of all the hotspots. Use "ubound" to find the number of hotspots in the list. You can then use "WindowHotspotList" to find details about each hotspot.

lua_example:
-- show all hotspots
hotspots = WindowHotspotList(win)

if hotspots then
  for _, v in ipairs (hotspots) do 
    Note (v) 
  end
end -- if any


name: WindowImageList
prototype: VARIANT WindowImageList(BSTR WindowName);
summary: Lists all images installed into a miniwindow
type_of_object: Method
doc_name: miniwindows
lua_notes: Lua returns nil if there are no images.
description:
This returns a list of all images loaded into this miniwindow. You could use this to find which images have been loaded, and then use WindowImageInfo to find information about each one.

WindowName - the name of the miniwindow to check for images.


For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

return_value:
If there are no images installed then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the image ids of all the hotspots. Use "ubound" to find the number of images in the list. You can then use "WindowImageInfo" to find details about each image.

see_also:
WindowCreate WindowCreateImage WindowDrawImage WindowImageInfo WindowImageOp WindowLoadImage WindowBlendImage

lua_example:
-- show all images
images = WindowImageList(win)

if images then
  for _, v in ipairs (images) do 
    Note (v) 
  end
end -- if any


name: GetDeviceCaps
prototype: long GetDeviceCaps(long Index);
summary: Gets screen device capabilities
return_value: The value corresponding to the requested index.
type_of_object: Method
see_also: GetSysColor GetSystemMetrics
doc_name: miniwindows
lua_example: print (GetDeviceCaps (8)) --> 1920 (horizontal width)
description:
This asks Windows for the capability of your output screen. The index specifies which attribute you are interested in, and it returns a number corresponding to that. Some useful indices are as follows:

0 : Device driver version
2 : Device classification
4 : Horizontal size in millimeters
6 : Vertical size in millimeters
8 : Horizontal width in pixels
10 : Vertical height in pixels
12 : Number of bits per pixel
14 : Number of planes
16 : Number of brushes the device has
18 : Number of pens the device has
20 : Number of markers the device has
22 : Number of fonts the device has
24 : Number of colors the device supports
26 : Size required for device descriptor
28 : Curve capabilities
30 : Line capabilities
32 : Polygonal capabilities
34 : Text capabilities
36 : Clipping capabilities
38 : Bitblt capabilities
40 : Length of the X leg
42 : Length of the Y leg
44 : Length of the hypotenuse
45 : Shading and blending caps
88 : Logical pixels/inch in X
90 : Logical pixels/inch in Y
104 : Number of entries in physical palette
106 : Number of reserved entries in palette
108 : Actual color resolution
116 : Current vertical refresh rate of the display device (for displays only) in Hz
117 : Horizontal width of entire desktop in pixels
118 : Vertical height of entire desktop in pixels
119 : Preferred blt alignment


For more information, see:

http://www.gammon.com.au/mushclient/mw_other.htm


name: WindowArc
summary: Draws an arc in a miniwindow
return_value: eNoSuchWindow - no such miniwindow ePenStyleNotValid - invalid pen style eOK - completed OK
type_of_object: Method
see_also: WindowBezier WindowCircleOp WindowCreate WindowDrawImage WindowLine WindowPolygon WindowRectOp
doc_name: miniwindows
lua_example: WindowArc (win, 20, 20, 80, 80, 30, 30, 120, 50, ColourNameToRGB ("green"), 0, 4)
prototype:
long WindowArc(BSTR WindowName, long Left, long Top, long Right, long Bottom, long x1, long y1, long x2, long y2, long PenColour, long PenStyle, long PenWidth);

description:
This draws an arc from x1,y1 to x2,y2 inside the box (Left,Top,Right,Bottom) with the designated pen.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Left, Top, Right, Bottom - describes the rectangle into which the arc must fit.

x1, y2 - the starting point for the arc - this point does not have to lie exactly on the arc.

x2, y2 - the ending point for the arc - this point does not have to lie exactly on the arc.

PenColour - the RGB colour for this pen

PenStyle - what style of pen to use:

0 - solid (an unbroken pen)
1 - dash: -------
2 - dot: .......
3 - dashdot: _._._._
4 - dashdotdot: _.._.._
5 - null (no pen)
6 - insideframe - a solid pen, drawn inside the shape

Also you can add into the style:

0x0000 - round ends   (0 = the default)
0x0100 - square ends  (256)
0x0200 - flat ends    (512)

0x0000 - round joins  (0 = the default)
0x1000 - bevel joins  (4096)
0x2000 - miter joins  (8192)


PenWidth - the width of the pen in pixels. For styles 1 to 4 only a width of 1 is valid.

For a particular shape, specify style 5 (no pen) if you only want to fill the shape, and not stroke it as well.


For more information, see:

http://www.gammon.com.au/mushclient/mw_shapes.htm

lua_notes:
You can use the following constants for the pen style:

miniwin.pen_solid = 0
miniwin.pen_dash = 1
miniwin.pen_dot = 2
miniwin.pen_dash_dot = 3
miniwin.pen_dash_dot_dot = 4
miniwin.pen_null = 5
miniwin.pen_inside_frame = 6

-- how lines join (eg. in polygons) (add this to the style)
   
miniwin.pen_join_round = 0
miniwin.pen_join_bevel = 4096
miniwin.pen_join_miter = 8192

-- how lines end (add this to the style)
   
miniwin.pen_endcap_round = 0
miniwin.pen_endcap_square = 256
miniwin.pen_endcap_flat = 512


name: WindowBezier
prototype: long WindowBezier(BSTR WindowName, BSTR Points, long PenColour, long PenStyle, long PenWidth);
summary: Draws a Bézier curve in a miniwindow
type_of_object: Method
see_also: WindowArc WindowCircleOp WindowCreate WindowDrawImage WindowLine WindowPolygon WindowRectOp
doc_name: miniwindows
lua_example: WindowBezier (win, "30, 20, 5, 90, 50, 90, 80, 30", ColourNameToRGB("blue"), 0, 2)
description:
Draws one or more Bézier splines. This function draws cubic Bézier splines by using the endpoints and control points specified by the Points parameter. The first spline is drawn from the first point to the fourth point by using the second and third points as control points. Each subsequent spline in the sequence needs exactly three more points: the end point of the previous spline is used as the starting point, the next two points in the sequence are control points, and the third is the end point.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Points - a string consisting of pairs of numbers, one for each point, in the format x1,y1,x2,y2 ...

For example: "20,50,180,50" would specify two points, one at 20,50 and one at 180,50.

You must have at least 4 points (the start, and 3 points per spline), which is 8 numbers. The number of numbers in the string must be even (divisible by two), as it takes a pair of numbers to specify one point. Also, since you need 3 points per spline, the number of numbers in the Points string must have a remainder of 2 when divided by 6 (3 points per spline, plus the start point).

PenColour - the RGB colour for this pen

PenStyle - what style of pen to use:

0 - solid (an unbroken pen)
1 - dash: -------
2 - dot: .......
3 - dashdot: _._._._
4 - dashdotdot: _.._.._
5 - null (no pen)
6 - insideframe - a solid pen, drawn inside the shape

Also you can add into the style:

0x0000 - round ends   (0 = the default)
0x0100 - square ends  (256)
0x0200 - flat ends    (512)

0x0000 - round joins  (0 = the default)
0x1000 - bevel joins  (4096)
0x2000 - miter joins  (8192)


PenWidth - the width of the pen in pixels. For styles 1 to 4 only a width of 1 is valid.

For a particular shape, specify style 5 (no pen) if you only want to fill the shape, and not stroke it as well.


For more information, see:

http://www.gammon.com.au/mushclient/mw_shapes.htm

return_value:
eNoSuchWindow - no such miniwindow

ePenStyleNotValid - invalid pen style

eInvalidNumberOfPoints - number of numbers supplied does not give a remainder of 2 after dividing by 6, or is less than 8. 

eOK - completed OK

lua_notes:
You can use the following constants for the pen style:

miniwin.pen_solid = 0
miniwin.pen_dash = 1
miniwin.pen_dot = 2
miniwin.pen_dash_dot = 3
miniwin.pen_dash_dot_dot = 4
miniwin.pen_null = 5
miniwin.pen_inside_frame = 6

-- how lines join (eg. in polygons) (add this to the style)
   
miniwin.pen_join_round = 0
miniwin.pen_join_bevel = 4096
miniwin.pen_join_miter = 8192

-- how lines end (add this to the style)
   
miniwin.pen_endcap_round = 0
miniwin.pen_endcap_square = 256
miniwin.pen_endcap_flat = 512


name: WindowCircleOp
summary: Draws ellipses, filled rectangles, round rectangles, chords, pies in a miniwindow
type_of_object: Method
see_also: WindowArc WindowBezier WindowCreate WindowDrawImage WindowLine WindowPolygon WindowRectOp
doc_name: miniwindows
prototype:
long WindowCircleOp(BSTR WindowName, short Action, long Left, long Top, long Right, long Bottom, long PenColour, long PenStyle, long PenWidth, long BrushColour, long BrushStyle, long Extra1, long Extra2, long Extra3, long Extra4);

description:
This draws an ellipse, rectangle, round rectangle, chord or pie, controlled by the Action parameter. 

Unlike WindowRectOp described above the rectangles drawn here can be filled with a brush, thus allowing you to have patterned interiors if desired.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Action - what sort of shape to draw, as follows:

1 = Ellipse
2 = Rectangle (however see below)
3 = Round Rectangle
4 = Chord
5 = Pie

Left, Top, Right, Bottom - describes the rectangle into which the shape must fit.

Note for rectangles: Due to the behaviour of the Windows drawing function which this calls, the rectangle excludes the bottom and right-hand edges (that is, stops one pixel short).



PenColour - the RGB colour for this pen

PenStyle - what style of pen to use:

0 - solid (an unbroken pen)
1 - dash: -------
2 - dot: .......
3 - dashdot: _._._._
4 - dashdotdot: _.._.._
5 - null (no pen)
6 - insideframe - a solid pen, drawn inside the shape

Also you can add into the style:

0x0000 - round ends   (0 = the default)
0x0100 - square ends  (256)
0x0200 - flat ends    (512)

0x0000 - round joins  (0 = the default)
0x1000 - bevel joins  (4096)
0x2000 - miter joins  (8192)


PenWidth - the width of the pen in pixels. For styles 1 to 4 only a width of 1 is valid.

For a particular shape, specify style 5 (no pen) if you only want to fill the shape, and not stroke it as well.

BrushColour - the RGB colour for this brush

BrushStyle - what style of brush to use:

0: solid (filled with a solid colour)
1: null (not filled)
2: hatch: horizontal
3: hatch: vertical
4: hatch: forwards diagonal
5: hatch: backwards diagonal
6: hatch: cross
7: hatch: diagonal cross
8: fine pattern
9: medium pattern
10: coarse pattern
11: waves - horizontal
12: waves - vertical


For more information, see:

http://www.gammon.com.au/mushclient/mw_shapes.htm

For actions 1 and 2 (ellipse and rectangle):

Extra1, Extra2, Extra3, Extra4 are ignored.


For action 3 (round rectangle):

Extra1 is the width of the ellipse used to draw the rounded corner.

Extra2 is the height of the ellipse used to draw the rounded corner.

Extra3, Extra4 are ignored.


For action 4 (chord):

Extra1, Extra2 is the x, y position of the chord's starting point.

Extra3, Extra4 is the x, y position of the chord's ending point.



For action 5 (pie):

Extra1, Extra2 is the x, y position of the pie's starting point.

Extra3, Extra4 is the x, y position of the pie's ending point.

return_value:
eNoSuchWindow - no such miniwindow

ePenStyleNotValid - invalid pen style

eBrushStyleNotValid - invalid brush style

eUnknownOption - Action not in list above

eOK - completed OK

lua_example:
-- Ellipses

WindowCircleOp (win, 1, 0, 0, 40, 40,    -- circle
                ColourNameToRGB("blue"), 0, 2, ColourNameToRGB("cyan"), 0)
WindowCircleOp (win, 1, 50, 20, 100, 100, -- ellipse
                ColourNameToRGB("magenta"), 0, 2, ColourNameToRGB("cyan"), 0)


-- Rectangles

WindowCircleOp (win, 2, 5, 5, 40, 40,   -- square
                ColourNameToRGB("blue"), 0, 3, ColourNameToRGB("cyan"), 8)
WindowCircleOp (win, 2, 50, 20, 95, 95, -- rectangle
                ColourNameToRGB("magenta"), 0, 3, ColourNameToRGB("cyan"), 11)


-- Round Rectangle

WindowCircleOp (win, 3, 15, 15, 90, 90,  -- round rectangle
        ColourNameToRGB("blue"), 0, 2, ColourNameToRGB("cyan"), 10, 25, 25)


-- Chord

WindowCircleOp (win, 4, 15, 15, 90, 90,  -- chord
        ColourNameToRGB("green"), 0, 2, ColourNameToRGB("cyan"), 0, 
        40, 10, 70, 95)

-- Pie

WindowCircleOp (win, 5, 15, 15, 90, 90,   -- pie
        ColourNameToRGB("green"), 0, 2, ColourNameToRGB("cyan"), 0, 
        60, 10, 80, 80)

lua_notes:
You can use the following constants for the action:

miniwin.circle_ellipse = 1
miniwin.circle_rectangle = 2
miniwin.circle_round_rectangle = 3
miniwin.circle_chord = 4
miniwin.circle_pie = 5

You can use the following constants for the pen style:

miniwin.pen_solid = 0
miniwin.pen_dash = 1
miniwin.pen_dot = 2
miniwin.pen_dash_dot = 3
miniwin.pen_dash_dot_dot = 4
miniwin.pen_null = 5
miniwin.pen_inside_frame = 6

-- how lines join (eg. in polygons) (add this to the style)
   
miniwin.pen_join_round = 0
miniwin.pen_join_bevel = 4096
miniwin.pen_join_miter = 8192

-- how lines end (add this to the style)
   
miniwin.pen_endcap_round = 0
miniwin.pen_endcap_square = 256
miniwin.pen_endcap_flat = 512


You can use the following constants for the brush style:

miniwin.brush_solid = 0
miniwin.brush_null = 1
miniwin.brush_hatch_horizontal = 2
miniwin.brush_hatch_vertical = 3
miniwin.brush_hatch_forwards_diagonal = 4
miniwin.brush_hatch_backwards_diagonal = 5
miniwin.brush_hatch_cross = 6
miniwin.brush_hatch_cross_diagonal = 7
miniwin.brush_fine_pattern = 8
miniwin.brush_medium_pattern = 9
miniwin.brush_coarse_pattern = 10
miniwin.brush_waves_horizontal = 11
miniwin.brush_waves_vertical = 12


name: WindowLine
summary: Draws a line in a miniwindow
return_value: eNoSuchWindow - no such miniwindow ePenStyleNotValid - invalid pen style eOK - completed OK
type_of_object: Method
see_also: WindowArc WindowBezier WindowCreate WindowDrawImage WindowCircleOp WindowPolygon WindowRectOp
doc_name: miniwindows
lua_example: WindowLine (win, 20, 20, 80, 80, ColourNameToRGB ("blue"), 0, 2)
prototype:
long WindowLine(BSTR WindowName, long x1, long y1, long x2, long y2, long PenColour, long PenStyle, long PenWidth);

description:
This draws a line from x1,y1 to x2,y2 with the designated pen.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

x1, y2 - the starting point for the line.

x2, y2 - the ending point for the line (note: the x2, y2 point is taken literally, zero or negative numbers have no special significance, as at version 4.38 of MUSHclient).

PenColour - the RGB colour for this pen

PenStyle - what style of pen to use:

0 - solid (an unbroken pen)
1 - dash: -------
2 - dot: .......
3 - dashdot: _._._._
4 - dashdotdot: _.._.._
5 - null (no pen)
6 - insideframe - a solid pen, drawn inside the shape

Also you can add into the style:

0x0000 - round ends   (0 = the default)
0x0100 - square ends  (256)
0x0200 - flat ends    (512)

0x0000 - round joins  (0 = the default)
0x1000 - bevel joins  (4096)
0x2000 - miter joins  (8192)


PenWidth - the width of the pen in pixels. For styles 1 to 4 only a width of 1 is valid.

For a particular shape, specify style 5 (no pen) if you only want to fill the shape, and not stroke it as well.

For more information, see:

http://www.gammon.com.au/mushclient/mw_shapes.htm

lua_notes:
You can use the following constants for the pen style:

miniwin.pen_solid = 0
miniwin.pen_dash = 1
miniwin.pen_dot = 2
miniwin.pen_dash_dot = 3
miniwin.pen_dash_dot_dot = 4
miniwin.pen_null = 5
miniwin.pen_inside_frame = 6

-- how lines join (eg. in polygons) (add this to the style)
   
miniwin.pen_join_round = 0
miniwin.pen_join_bevel = 4096
miniwin.pen_join_miter = 8192

-- how lines end (add this to the style)
   
miniwin.pen_endcap_round = 0
miniwin.pen_endcap_square = 256
miniwin.pen_endcap_flat = 512


name: WindowPolygon
summary: Draws a polygon in a miniwindow
type_of_object: Method
see_also: WindowArc WindowBezier WindowCreate WindowDrawImage WindowCircleOp WindowLine WindowRectOp
doc_name: miniwindows
prototype:
long WindowPolygon(BSTR WindowName, BSTR Points, long PenColour, long PenStyle, long PenWidth, long BrushColour, long BrushStyle, BOOL Close, BOOL Winding);

description:
This draws a polygon (series of straight lines) connecting the specified points, with the designated pen and filled with the designated brush.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Points - a string consisting of pairs of numbers, one for each point, in the format x1,y1,x2,y2 ...

For example: "20,50,180,50" would specify two points, one at 20,50 and one at 180,50.

You must have at least 2 points (the start and end), which is 4 numbers. The number of numbers in the string must be even (divisible by two), as it takes a pair of numbers to specify one point.

PenColour - the RGB colour for this pen

PenStyle - what style of pen to use:

0 - solid (an unbroken pen)
1 - dash: -------
2 - dot: .......
3 - dashdot: _._._._
4 - dashdotdot: _.._.._
5 - null (no pen)
6 - insideframe - a solid pen, drawn inside the shape

Also you can add into the style:

0x0000 - round ends   (0 = the default)
0x0100 - square ends  (256)
0x0200 - flat ends    (512)

0x0000 - round joins  (0 = the default)
0x1000 - bevel joins  (4096)
0x2000 - miter joins  (8192)


PenWidth - the width of the pen in pixels. For styles 1 to 4 only a width of 1 is valid.

For a particular shape, specify style 5 (no pen) if you only want to fill the shape, and not stroke it as well.

BrushColour - the RGB colour for this brush

BrushStyle - what style of brush to use:

0: solid (filled with a solid colour)
1: null (not filled)
2: hatch: horizontal
3: hatch: vertical
4: hatch: forwards diagonal
5: hatch: backwards diagonal
6: hatch: cross
7: hatch: diagonal cross
8: fine pattern
9: medium pattern
10: coarse pattern
11: waves - horizontal
12: waves - vertical

BrushColour, Brushstyle - the brush colour and style as described at the top of this page.

Close - if true, the polygon is closed by connecting the last point to the first one, if necessary

Winding - if true the polygon is filled using the "winding" algorithm, if false it is filled using the "alternate" algorithm.

When the polygon-filling mode is "alternate", the system fills the area between odd-numbered and even-numbered polygon sides on each scan line. That is, the system fills the area between the first and second side, between the third and fourth side, and so on. This mode is the default.

When the polygon-filling mode is "winding", the system uses the direction in which a figure was drawn to determine whether to fill an area. Each line segment in a polygon is drawn in either a clockwise or a counterclockwise direction. Whenever an imaginary line drawn from an enclosed area to the outside of a figure passes through a clockwise line segment, a count is incremented. When the line passes through a counterclockwise line segment, the count is decremented. The area is filled if the count is nonzero when the line reaches the outside of the figure.


For more information, see:

http://www.gammon.com.au/mushclient/mw_shapes.htm

return_value:
eNoSuchWindow - no such miniwindow

ePenStyleNotValid - invalid pen style

eBrushStyleNotValid - invalid brush style

eInvalidNumberOfPoints - must have at least 2 points (4 numbers) and the number of numbers must be divisible by 2

eOK - completed OK

lua_example:
WindowPolygon (win, "20,50,180,50,180,20,230,70,180,120,180,90,20,90",
                        ColourNameToRGB("cyan"), 0, 3,   -- pen (solid, width 3)
                        ColourNameToRGB("yellow"), 0,    -- brush (solid)
                        true,    -- fill
                        false)   -- alternate fill

lua_notes:
You can use the following constants for the pen style:

miniwin.pen_solid = 0
miniwin.pen_dash = 1
miniwin.pen_dot = 2
miniwin.pen_dash_dot = 3
miniwin.pen_dash_dot_dot = 4
miniwin.pen_null = 5
miniwin.pen_inside_frame = 6

-- how lines join (eg. in polygons) (add this to the style)
   
miniwin.pen_join_round = 0
miniwin.pen_join_bevel = 4096
miniwin.pen_join_miter = 8192

-- how lines end (add this to the style)
   
miniwin.pen_endcap_round = 0
miniwin.pen_endcap_square = 256
miniwin.pen_endcap_flat = 512


You can use the following constants for the brush style:

miniwin.brush_solid = 0
miniwin.brush_null = 1
miniwin.brush_hatch_horizontal = 2
miniwin.brush_hatch_vertical = 3
miniwin.brush_hatch_forwards_diagonal = 4
miniwin.brush_hatch_backwards_diagonal = 5
miniwin.brush_hatch_cross = 6
miniwin.brush_hatch_cross_diagonal = 7
miniwin.brush_fine_pattern = 8
miniwin.brush_medium_pattern = 9
miniwin.brush_coarse_pattern = 10
miniwin.brush_waves_horizontal = 11
miniwin.brush_waves_vertical = 12


name: WindowRectOp
summary: Draws a rectangle in a miniwindow
type_of_object: Method
see_also: WindowArc WindowBezier WindowCreate WindowDrawImage WindowCircleOp WindowLine WindowPolygon
doc_name: miniwindows
prototype:
long WindowRectOp(BSTR WindowName, short Action, long Left, long Top, long Right, long Bottom, long Colour1, long Colour2);

description:
This draws a rectangle in various styles, controlled by the Action parameter.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Action - what sort of rectangle to draw, as follows:

1 = Frame by a single pixel wide line in Colour1
2 = Fill the entire rectangle by Colour1
3 = InvertRect - the colour on the miniwindow inside that rectangle is inverted
4 = Draw a "3D-style" rectangle in two colours, a single pixel wide (Colour1 is top and left edge colour, Colour2 is bottom and right edge colour)
5 = Draw Edge (draws a 3d-style edge with optional fill)
6 = Flood Fill Border (fills to border specified by Colour1) - the filling commences at the pixel designated by Left, Top and continues until it runs out of pixels that colour. The fill colour is specified by Colour2.
7 = Flood Fill Surface (fills while on surface specified by Colour1) - the filling commences at the pixel designated by Left, Top and continues until it is on pixels that colour. The fill colour is specified by Colour2.

Left, Top, Right, Bottom - describes the rectangle to be drawn.

Colour1 - the colour to draw the rectangle in (or fill it). For Action 5, this must be one of:

5 : Raised
6 : Etched
9 : Bump
10 : Sunken

Colour2 - the colour used by Action 4 for the bottom and right edge. Also it is the colour used for flood filling (Actions 6 and 7). For Action 5, this is:

0x03 (3) top left
0x06 (6) top right
0x09 (9) bottom left
0x0c (12) bottom right
0x0f (15) rect

Diagonal lines:

0x13 (19) diagonal - end top left
0x16 (22) diagonal - end top right
0x19 (25) diagonal - end bottom left
0x1c (28) diagonal - end bottom right

For Action 5 you can also add in the following values to modify the behaviour of the drawn rectangle:

0x0800 - Fill in the middle
0x1000 - For softer buttons
0x4000 - For flat rather than 3D borders
0x8000 - For monochrome borders


For more information, see:

http://www.gammon.com.au/mushclient/mw_shapes.htm

return_value:
eNoSuchWindow - no such miniwindow

eUnknownOption - Action not in list above

eBadParameter - edge parameter invalid

eOK - completed OK

lua_example:
WindowRectOp (win, 1, 20, 20, 70, 70, ColourNameToRGB("blue"))  -- outline

WindowRectOp (win, 2, 50, 20, 80, 80, ColourNameToRGB("green"))  -- filled

WindowRectOp (win, 3, 5, 5, 90, 90, 0)   -- invert 

WindowRectOp (win, 4, 50, 30, 70, 70, ColourNameToRGB("springgreen"), ColourNameToRGB("green"))

WindowRectOp (win, 5, 30, 30, 70, 70, 5, 15)  -- raised, not filled

WindowRectOp (win, 5, 30, 30, 70, 70, 5, 15 + 0x800)  -- raised, filled

WindowRectOp (win, 5, 30, 30, 70, 70, 5, 15 + 0x800 + 0x1000)  -- raised, filled, softer

WindowRectOp (win, 5, 30, 30, 70, 70, 5, 15 + 0x800 + 0x1000 + 0x4000)  -- raised, filled, softer, flat

WindowRectOp (win, 5, 30, 30, 70, 70, 6, 15 + 0x800)  -- etched, filled

lua_notes:
You can use the following constants for the action:

miniwin.rect_frame = 1
miniwin.rect_fill = 2
miniwin.rect_invert = 3
miniwin.rect_3d_rect = 4
miniwin.rect_draw_edge = 5
miniwin.rect_flood_fill_border = 6
miniwin.rect_flood_fill_surface = 7

You can use the following constants for the Colour1 parameter (argument 7) for action 5 (rect_draw_edge):

miniwin.rect_edge_raised = 5
miniwin.rect_edge_etched = 6
miniwin.rect_edge_bump = 9
miniwin.rect_edge_sunken = 10

You can use the following constants for the Colour2 parameter (argument 8) for action 5 (rect_draw_edge):

miniwin.rect_edge_at_top_left = 3
miniwin.rect_edge_at_top_right = 6
miniwin.rect_edge_at_bottom_left = 9
miniwin.rect_edge_at_bottom_right = 12
miniwin.rect_edge_at_all = 15
miniwin.rect_diagonal_end_top_left = 19
miniwin.rect_diagonal_end_top_right = 22
miniwin.rect_diagonal_end_bottom_left = 25
miniwin.rect_diagonal_end_bottom_right = 28

You can add in these additional constants to the Colour2 parameter (argument 8) for action 5 (rect_draw_edge):

miniwin.rect_option_fill_middle = 2048
miniwin.rect_option_softer_buttons = 4096
miniwin.rect_option_flat_borders = 16384
miniwin.rect_option_monochrom_borders = 32768


name: WindowCreate
summary: Creates a miniwindow
type_of_object: Method
see_also: WindowInfo WindowList WindowShow WindowDelete WindowResize
doc_name: miniwindows
prototype:
long WindowCreate(BSTR WindowName, long Left, long Top, long Width, long Height, short Position, long Flags, long BackgroundColour);

description:
This creates (or re-creates) a miniwindow of the given name. It is not initially shown so it will be invisible until you call WindowShow. If there is an existing, visible, window of that name, then it will be marked invisible, so you will need to call WindowShow to make it visible again.

If you want to change the size of a miniwindow you don't need to delete it, simply call WindowCreate again, which causes it to be recreated in the new location / size. However you can call WindowDelete to completely delete an existing miniwindow.

Alternatively, call WindowResize which resizes the window, keeping all fonts, images and hotspots.

It is reasonable to use WindowCreate to create a very small window (eg. 0 x 0 pixels) simply to load images or fonts into it. Thus you can find out font sizes, in order to calculate what size window needs to be re-created, so it is the correct size to hold a particular piece of text.

If you call WindowCreate on an existing window then:

* The existing offscreen image will be discarded, and the memory it used freed.

* A new offscreen image will be created, using the new dimensions. Thus you can use WindowCreate to resize a window. For example, you might do this for an inventory window, if you get more inventory.

* The image will be cleared to the background colour you specify.

* Any hotspots you added are removed - unless flag 0x10 is set (create_keep_hotspots), see below. The assumption is that if you are starting drawing from scratch, any hotspot items will probably appear in a different place.

* The window's "show" flag is set to false. Thus you need to call WindowShow before it will become visible.

PARAMETERS:

WindowName - the name we are calling it - needed for all subsequent operations on this miniwindow. We suggest you use GetPluginID () to get a unique name for this window. If you plan to use more than one window in a plugin, simply append "A", "B", etc. to the plugin ID. The name may not be the empty string.

NOTE: Window names are case-sensitive.

Left, Top - the top/left corner to position it, inside the MUSHclient output window.

(This may be 0,0 if you are using auto-positioning).

Width, Height - the width and height of the window, in pixels. The example window above is 200, 200. The minimum size is 0, 0.

These are required, and lock in the size of the window for subsequent drawing operations. Any attempts to draw outside these boundaries will be clipped.

Position - a number indicating where you want the window positioned on the screen. Whenever the screen is resized or redrawn the contents of the window are drawn in the requested position:

0 = stretch to output view size
1 = stretch with aspect ratio
2 = strech to owner size
3 = stretch with aspect ratio
4 = top left
5 = center left-right at top
6 = top right
7 = on right, center top-bottom
8 = on right, at bottom
9 = center left-right at bottom
10 = on left, at bottom
11 = on left, center top-bottom
12 = centre all
13 = tile

Positions 0 to 3 probably aren't that useful (they are also used for loading background images), and position 13 (tile) would probably not be used often either. However you might use these if you set the "draw underneath" flag described below, so that a subtle window could appear under main output window.

The corner positions (4, 6, 8, 10) always put the miniwindow in that corner, and 12 (centre all) always puts the window dead-centre of the main output window.

The other positions (5, 7, 9, 11) are used for centering the window between the corners. MUSHclient tries to fit the miniwindow exactly in the middle between any corner windows. Also, if more than one window is designated as centered on that side (eg., the right side) it tries to fit them all in, evenly spaced.

If the centered windows can't all be fitted, some are temporarily hidden until they do, in order to avoid overlaps.

Flags - this can be a combination of the following bits (that is, add them together if you want more than one):

1 - Draw underneath. If set, the miniwindow is drawn beneath the scrolling text in the output window.

WARNING: If you set the "draw underneath" flag then you cannot use hotspots, as the hotspots are underneath the text and will not be detected.

2 - Absolute location. If set, the miniwindow is not subject to auto positioning (so the Position argument is ignored), and it is located exactly at the Left, Top position designated in the function call. By setting this bit you have absolute control over where the window will appear.

4 - Transparent. If set, whenever a pixel in the contents of the window matches the BackgroundColour, it is not drawn, and the text underneath shows through. This lets you make odd-shape windows like stars or circles, by filling the outside (the part you don't want to see) with the background colour.

8 - Ignore mouse. If set, this miniwindow is not considered for mouse-over, mouse-down, mouse-up events. 

16 - Keep existing hotspots. If set, hotspots are not deleted if you are recreating an existing miniwindow.


WARNING: If you set the "ignore mouse" flag then you cannot use hotspots, as mouse clicks and movement will not be detected.


BackgroundColour - this is the RGB code for the colour that the window is initially filled with, and is used when doing transparent drawing, as described above.


For more information, see:

http://www.gammon.com.au/mushclient/mw_creation.htm

return_value:
eNoNameSpecified - miniwindow name must be specified
eBadParameter - width or height less than zero
eOK - success

lua_example:
win = "win_" .. GetPluginID ()  -- get a unique name
WindowCreate (win, 0, 0, 200, 200, miniwin.pos_center_all, 0, ColourNameToRGB("white"))  -- create window
WindowShow (win,  true)  -- show it

lua_notes:
You can use the following constants for the position:

miniwin.pos_stretch_to_view = 0
miniwin.pos_stretch_to_view_with_aspect = 1
miniwin.pos_stretch_to_owner = 2
miniwin.pos_stretch_to_owner_with_aspect = 3
miniwin.pos_top_left = 4
miniwin.pos_top_center = 5
miniwin.pos_top_right = 6
miniwin.pos_center_right = 7
miniwin.pos_bottom_right = 8
miniwin.pos_bottom_center = 9
miniwin.pos_bottom_left = 10
miniwin.pos_center_left = 11
miniwin.pos_center_all = 12
miniwin.pos_tile = 13


You can use the following constants for the flags:

miniwin.create_underneath = 1
miniwin.create_absolute_location = 2
miniwin.create_transparent = 4
miniwin.create_ignore_mouse = 8
miniwin.create_keep_hotspots = 16


name: WindowShow
prototype: long WindowShow(BSTR WindowName, BOOL Show);
summary: Shows or hides a miniwindow
return_value: eNoSuchWindow - no such miniwindow eOK - success
type_of_object: Method
see_also: WindowInfo WindowList WindowCreate
doc_name: miniwindows
description:
This shows or hides the designated window.

WindowName - the name of an existing miniwindow.

Show - true to display the window at its designated place, false to hide it.

Creating and showing windows are separate operations. This is because you may want to maintain something like an inventory list, or quest objectives, but not necessarily have space on the screen for them at a particular moment. By creating the window early on, you can draw to it (offscreen), add or remove items, and generally keep it up-to-date as events occur on the game. However when the player actually wants to see the window s/he may hit a hotkey or type an alias, which simply causes the window to be shown (or hidden).

Calling WindowShow forces a window refresh, so the screen will be updated with the new miniwindow (or absence, as the case may be).

If you have changed the miniwindow, you may not want to call WindowShow (in case they currently want it hidden). In this case you can call Redraw () instead, to cause the main output window to be redrawn, without changing the status of any miniwindows.


For more information, see:

http://www.gammon.com.au/mushclient/mw_creation.htm

lua_example:
WindowShow (win, true)  -- show window, refresh screen

WindowShow (win, false) -- hide window, refresh screen


name: WindowPosition
prototype: long WindowPosition(BSTR WindowName, long Left, long Top, short Position, long Flags);
summary: Moves a miniwindow
return_value: eNoSuchWindow - no such miniwindow eOK - success
type_of_object: Method
see_also: WindowInfo WindowList WindowCreate
doc_name: miniwindows
description:
This lets you move a miniwindow. This is only really useful if you are setting the "Absolute location" flag when creating it. In this case, if you notice the output window has been resized, you may want to resposition the window, without having to re-create it, and redraw all its contents.

The output window is scheduled for a redraw if this function is successful.


WindowName - the name of an existing miniwindow.

Left, Top - the top/left corner to position it, inside the MUSHclient output window.

(This may be 0,0 if you are using auto-positioning).

Position - a number indicating where you want the window positioned on the screen. Whenever the screen is resized or redrawn the contents of the window are drawn in the requested position:

0 = strech to output view size
1 = stretch with aspect ratio
2 = strech to owner size
3 = stretch with aspect ratio
4 = top left
5 = center left-right at top
6 = top right
7 = on right, center top-bottom
8 = on right, at bottom
9 = center left-right at bottom
10 = on left, at bottom
11 = on left, center top-bottom
12 = centre all
13 = tile

Flags - this can be a combination of the following bits (that is, add them together if you want more than one):

1 - Draw underneath. If set, the miniwindow is drawn beneath the scrolling text in the output window.

2 - Absolute location. If set, the miniwindow is not subject to auto positioning (so the Position argument is ignored), and it is located exactly at the Left, Top position designated in the function call. By setting this bit you have absolute control over where the window will appear.

4 - Transparent. If set, whenever a pixel in the contents of the window matches the BackgroundColour, it is not drawn, and the text underneath shows through. This lets you make odd-shape windows like stars or circles, by filling the outside (the part you don't want to see) with the background colour.

8 - Ignore mouse. If set, this miniwindow is not considered for mouse-over, mouse-down, mouse-up events. 

16 - Keep existing hotspots. If set, hotspots are not deleted if you are recreating an existing miniwindow (with WindowCreate).


For more information, see:

http://www.gammon.com.au/mushclient/mw_creation.htm

lua_notes:
You can use the following constants for the position:

miniwin.pos_stretch_to_view = 0
miniwin.pos_stretch_to_view_with_aspect = 1
miniwin.pos_stretch_to_owner = 2
miniwin.pos_stretch_to_owner_with_aspect = 3
miniwin.pos_top_left = 4
miniwin.pos_top_center = 5
miniwin.pos_top_right = 6
miniwin.pos_center_right = 7
miniwin.pos_bottom_right = 8
miniwin.pos_bottom_center = 9
miniwin.pos_bottom_left = 10
miniwin.pos_center_left = 11
miniwin.pos_center_all = 12
miniwin.pos_tile = 13


You can use the following constants for the flags:

miniwin.create_underneath = 1
miniwin.create_absolute_location = 2
miniwin.create_transparent = 4
miniwin.create_ignore_mouse = 8
miniwin.create_keep_hotspots = 16


name: WindowCreateImage
summary: Creates an image in a miniwindow
return_value: eNoSuchWindow - no such miniwindow eOK - completed OK
type_of_object: Method
see_also: WindowCreate WindowImageList WindowDrawImage WindowImageInfo WindowImageOp WindowLoadImage
doc_name: miniwindows
prototype:
long WindowCreateImage(BSTR WindowName, BSTR ImageId, long Row8, long Row7, long Row6, long Row5, long Row4, long Row3, long Row2, long Row1);

description:
This creates a small image (bitmap) by specifying the bit pattern for an 8 x 8 bit image. This is primarily intended for making patterns for use with WindowImageOp, described elsewhere. By designing suitable patterns you could make grass, waves, or other landscape effects for use in maps.

WindowName - the name of an existing miniwindow.

ImageId - the image id to store this image under.

Row1, Row2, Row3, Row4, Row5, Row6, Row7, Row8 - the bit pattern for each row

The easiest way of making your own pattern is to use Lua's tonumber function and work in binary. When doing that, each '1' represents a bit that is set (and is thus in the PenColour) and each '0' represents a bit that is clear (and is thus in the BrushColour).


For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

lua_example:
WindowCreateImage (win, "im2", 
        tonumber ("11001100", 2),  -- row 8
        tonumber ("11001100", 2),  -- row 7
        tonumber ("00110011", 2),  -- row 6
        tonumber ("00110011", 2),  -- row 5
        tonumber ("11001100", 2),  -- row 4
        tonumber ("11001100", 2),  -- row 3
        tonumber ("00110011", 2),  -- row 2
        tonumber ("00110011", 2))  -- row 1


name: WindowLoadImage
prototype: long WindowLoadImage(BSTR WindowName, BSTR ImageId, BSTR FileName);
summary: Loads an image into a miniwindow from a disk file
type_of_object: Method
see_also: WindowCreate WindowImageList WindowDrawImage WindowImageInfo WindowImageOp WindowCreateImage
doc_name: miniwindows
description:
This loads the specified image into the miniwindow, and remembers it by the nominated "image id". The image id is later used for drawing this image. Loading does not draw it, it simply reads it from disk ready for drawing later.

Also see below in the Lua notes for WindowLoadImageMemory which loads an image loaded into memory.

WindowName - the name of an existing miniwindow.

ImageId - the image id to be associated with this particular image.

FileName - the disk file to load the image from. It should be a BMP or PNG file, not a GIF, TIF or other file type. If the filename is the empty string (ie. "") then any existing image matching the ImageId is deleted.

For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

If the loaded image is a PNG file, then it will have 24 bits per pixel if it does not have an alpha channel, and 32 bits per pixel if it has an alpha channel. You can use WindowImageInfo with selector 6 to find the number of bits per pixel of the loaded image.

return_value:
eNoSuchWindow - no such miniwindow

eFileNotFound - specified file was not found

eUnableToLoadImage - can't load image - perhaps it is not a BMP or PNG file

eOK - completed OK

lua_example:
WindowLoadImage (win, "im1", "C:/program files/mushclient/leaf.bmp")
WindowLoadImage (win, "im2", "C:/program files/mushclient/background.png")

lua_notes:
From version 4.42 onwards, Lua also supports WindowLoadImageMemory which loads an image file loaded into a memory buffer.

In this case the third argument is the memory buffer, not the file name.

local f = assert (io.open ("sword.png", "rb"))
local image_data = f:read ("*a")  -- read all of it
f:close ()  -- close it

WindowLoadImageMemory (win, "im", image_data) -- load image from memory
WindowDrawImage (win, "im", 20, 20, 0, 0, 1)  -- draw it


For WindowLoadImageMemory only PNG files are supported, not BMP ones.

WindowLoadImageMemory also supports an optional fourth argument. If true, the blue channel is swapped with the alpha channel.  Thus, code like below would load the image  into "ima", and then show it in the miniwindow, showing only the alpha mask:

WindowLoadImageMemory (win, "ima", image_data, true)
WindowBlendImage (win, "ima", 0, 0, 0, 0, 59, 1)


name: WindowDrawImage
summary: Draws an image into a miniwindow
type_of_object: Method
doc_name: miniwindows
prototype:
long WindowDrawImage(BSTR WindowName, BSTR ImageId, long Left, long Top, long Right, long Bottom, short Mode, long SrcLeft, long SrcTop, long SrcRight, long SrcBottom);

description:
This copies an image to the miniwindow.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, Repaint, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

ImageId - an image id that you have loaded.

Left, Top, Right, Bottom - describes the rectangle to be drawn to.

Mode - the method of drawing the image:

1 - Copy without stretching to the destination position. The image is not clipped, so only the Left and Top parameters are used - the full image is copied to that position.

To copy less than the full image you would need to use the SrcLeft, SrcTop, SrcRight, SrcBottom parameters to specify a smaller part of the image.

2 - Stretch or shrink the image appropriately to fit into the rectangle: Left, Top, Right, Bottom.

3 - Copy without stretching to the position Left, Top. However this is a transparent copy, where the pixel at the left,top corner (pixel position 0,0) is considered the transparent colour. Any pixels that exactly match that colour are not copied. WARNING - do not choose black or white as the transparent colour as that throws out the calculations. Choose some other colour (eg. purple) - you won't see that colour anyway.

SrcLeft, SrcTop, SrcRight, SrcBottom - the source rectangle in the original image (use 0,0,0,0 to get the whole image). Negative numbers for the SrcRight and SrcBottom parameters represent an offset from the bottom or right edge.

The intention of allowing sub-images was so that you could make up a map by having lots of small images (eg. houses, trees, rocks). Now instead of having to load hundreds of tiny image files into memory, which would doubtless take a while to open all those files, you open a single, larger, file in which the various sub-images are "tiled". For example, you might allocate a 32 x 32 pixel square for each image. Now by selecting the appropriate tile you can copy the sub-image from the main image.

For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

To draw images which have alpha channels, see WindowDrawImageAlpha.

Note that if you draw a monchrome image, such as one set up by WindowCreateImage then the pen colour from the most recent drawing operation is used as the foreground colour, and the brush colour for the background colour. Thus you may want to draw a small rectangle (eg. 1 x 1 pixel) with WindowCircleOp to establish those colours first.

return_value:
eNoSuchWindow - no such miniwindow

eImageNotInstalled - that image was not loaded with WindowLoadImage or WindowLoadImageMemory

eBadParameter - drawing mode not in list above

eOK - completed OK

see_also:
WindowCreate WindowImageList WindowDrawImage WindowImageInfo WindowImageOp WindowCreateImage WindowDrawImageAlpha WindowTransformImage

lua_example:
WindowDrawImage (win, "im", 20, 20, 0, 0, 1)  -- straight copy

WindowDrawImage (win, "im", 20, 20, -20, -20, 2)  -- stretch

WindowDrawImage (win, "im", 20, 20, -20, -20, 3)  -- transparent

lua_notes:
You can use the following constants for the mode:

miniwin.image_copy = 1
miniwin.image_stretch = 2
miniwin.image_transparent_copy = 3


name: WindowImageOp
summary: Draws an ellipse, rectangle or round rectangle, filled with an image
type_of_object: Method
see_also: WindowCreate WindowImageList WindowDrawImage WindowImageInfo WindowCreateImage
doc_name: miniwindows
prototype:
long WindowImageOp(BSTR WindowName, short Action, long Left, long Top, long Right, long Bottom, long PenColour, long PenStyle, long PenWidth, long BrushColour, BSTR ImageId, long EllipseWidth, long EllipseHeight);

description:
This draws an ellipse, rectangle, round rectangle, controlled by the Action parameter. The specified shape is filled with a previously-loaded image.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Action - what sort of shape to draw, as follows:

1 = Ellipse
2 = Rectangle
3 = Round Rectangle

Left, Top, Right, Bottom - describes the rectangle into which the shape must fit.

PenColour - the RGB colour for this pen

PenStyle - what style of pen to use:

0 - solid (an unbroken pen)
1 - dash: -------
2 - dot: .......
3 - dashdot: _._._._
4 - dashdotdot: _.._.._
5 - null (no pen)
6 - insideframe - a solid pen, drawn inside the shape

Also you can add into the style:

0x0000 - round ends   (0 = the default)
0x0100 - square ends  (256)
0x0200 - flat ends    (512)

0x0000 - round joins  (0 = the default)
0x1000 - bevel joins  (4096)
0x2000 - miter joins  (8192)


PenWidth - the width of the pen in pixels. For styles 1 to 4 only a width of 1 is valid.

For a particular shape, specify style 5 (no pen) if you only want to fill the shape, and not stroke it as well.

BrushColour - the colour used for drawing the background, when displaying monochrome bitmaps.

ImageId - an image id that you have loaded.

EllipseWidth, EllipseHeight - the dimensions of the ellipse in the corner of a round rectangle, if applicable.


For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

return_value:
eNoSuchWindow - no such miniwindow

eImageNotInstalled - that image was not loaded with WindowLoadImage

ePenStyleNotValid - invalid pen style

eUnknownOption - drawing mode not in list above

eOK - completed OK

lua_example:
WindowImageOp (win, 1, 20, 20, 150, 150,    -- circle
              ColourNameToRGB("blue"), 0, 2, 
              ColourNameToRGB("cyan"), "im")

WindowImageOp (win, 2, 0, 0, 0, 0,    -- rectangle 
              ColourNameToRGB("blue"), 5, 1, 
              ColourNameToRGB("cyan"), "im")


WindowImageOp (win, 3, 20, 20, 160, 160,    -- round rectangle
              ColourNameToRGB("blue"), 0, 3, 
              ColourNameToRGB("cyan"), "im", 
              20, 20)

lua_notes:
You can use the following constants for the action:

miniwin.image_fill_ellipse = 1
miniwin.image_fill_rectangle = 2
miniwin.image_fill_round_fill_rectangle = 3


You can use the following constants for the pen style:

miniwin.pen_solid = 0
miniwin.pen_dash = 1
miniwin.pen_dot = 2
miniwin.pen_dash_dot = 3
miniwin.pen_dash_dot_dot = 4
miniwin.pen_null = 5
miniwin.pen_inside_frame = 6

-- how lines join (eg. in polygons) (add this to the style)
   
miniwin.pen_join_round = 0
miniwin.pen_join_bevel = 4096
miniwin.pen_join_miter = 8192

-- how lines end (add this to the style)
   
miniwin.pen_endcap_round = 0
miniwin.pen_endcap_square = 256
miniwin.pen_endcap_flat = 512


name: WindowFont
summary: Loads a font into a miniwindow
type_of_object: Method
see_also: WindowCreate WindowFontInfo WindowFontList WindowText WindowTextWidth
doc_name: miniwindows
prototype:
long WindowFont(BSTR WindowName, BSTR FontId, BSTR FontName, double Size, BOOL Bold, BOOL Italic, BOOL Underline, BOOL Strikeout, short Charset, short PitchAndFamily);

description:
This loads the specified font into the miniwindow, and remembers it by the nominated "font id". The font id is later used for drawing in this font. You do not need to specify a colour, that is done when the text is actually drawn.

WindowName - the name of an existing miniwindow.

FontId - the font id to be associated with this particular font and size. If you are only planning to use one or two fonts you might call them "f1" and "f2". For more complex situations you might call them something like "heading", "body", "boldbody", "footer" etc. 

If you use an existing FontId then the existing font is deleted and replaced by the one specified now.

FontName - the name of the font (for example, "Lucida Console", "Comic Sans MS", "Fixedsys"). If the FontName is an empty string (ie. name is "") and the Size is zero, then any existing font of the same FontId is deleted (and no new font is added).

If you are using Lua scripting, you can use the utils.getfontfamilies function to find which font names are actually installed.

Size - the size of the font in points

Bold - true if you want the bold version of the font

Italic - true if you want the italic version of the font

Underline - true if you want the underline version of the font

Strikeout - true if you want the strikeout version of the font

Charset - The character set wanted. Some possible values are:

0 - ANSI
1 - Default
2 - Symbol

Unless you have a reason otherwise, use 1 (default) which is the default value for Lua.

PitchAndFamily - the requested pitch and family

You can add together the following values:

Family

0 - Don't care
16 - Roman (variable width, serif, eg. Times Roman)
32 - Swiss (variable width, sans-serif, eg. Helvetica)
48 - Modern (fixed width, serif or sans-serif - eg. Courier)
64 - Script (cursive, etc.)
80 - Decorative (Old English, etc.)

Pitch

0 - Default
1 - Fixed pitch
2 - Variable pitch
8 - Mono font


Truetype

4 - Use Truetype font

A reasonable entry would be 0 - for don't care. Or, if you wanted a variable width, serif, truetype font, you could specify 20 (which is 16 + 4).

For more information, see:

http://www.gammon.com.au/mushclient/mw_text.htm

return_value:
eNoSuchWindow - no such miniwindow

eCannotAddFont - cannot add it (perhaps font does not exist)

eOK - completed OK

lua_example:
-- Trebuchet MS, 28 point, bold
WindowFont (win, "heading", "Trebuchet MS", 28, true, false, false, false)

lua_notes:
You can use the following constants for the charset argument:

miniwin.font_charset_ansi = 0
miniwin.font_charset_default = 1
miniwin.font_charset_symbol = 2


You can use the following constants for the PitchAndFamily argument (these can be added together):

miniwin.font_family_any = 0
miniwin.font_family_roman = 16
miniwin.font_family_swiss = 32
miniwin.font_family_modern = 48
miniwin.font_family_script = 64
miniwin.font_family_decorative = 80

miniwin.font_pitch_default = 0
miniwin.font_pitch_fixed = 1
miniwin.font_pitch_variable = 2
miniwin.font_truetype = 4
miniwin.font_pitch_monospaced = 8


name: WindowText
summary: Draws text into a miniwindow
type_of_object: Method
see_also: WindowCreate WindowFontInfo WindowFontList WindowFont WindowTextWidth
doc_name: miniwindows
prototype:
long WindowText(BSTR WindowName, BSTR FontId, BSTR Text, long Left, long Top, long Right, long Bottom, long Colour, BOOL Unicode);

description:
This draws some text in miniwindow.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

This function does not do anything special for newlines, carriage-returns, tabs etc.  Probably a box or graphical character will be drawn if you attempt to use them. To handle changing lines you will need to do a second WindowText with the Y (Top) parameter increased. To handle tabbing you would need to increase the X (Left) parameter.

Parameters:

WindowName - the name of an existing miniwindow.

FontId - a font id that you have loaded.

Text - the text to be drawn (maximum of 8192 characters)

Left, Top, Right, Bottom - describes the rectangle to be drawn.

Colour - what colour to draw the text in (RGB)

Unicode - if true, the text is Unicode text in UTF-8 format



For more information, see:

http://www.gammon.com.au/mushclient/mw_text.htm

return_value:
If successful, returns the number of pixels the text took horizontally. Thus, by adding that to the "Left" parameter, you can draw some more text to the right of what was just drawn.

If unsuccessful, returns a negative number as follows:

-1 : That window name does not exist
-2 : That font was not loaded
-3 : For Unicode, invalid UTF-8 sequence

lua_example:
WindowText (win, "f", "Quest Log",
            5, 10, 0, 0,  -- rectangle
            ColourNameToRGB ("blue"), 
            false) -- not Unicode
                
WindowText (win, "f2", "MUSHclient",
            5, 40, 0, 0,  -- rectangle
            ColourNameToRGB ("saddlebrown"), 
            false) -- not Unicode


name: WindowTextWidth
prototype: long WindowTextWidth(BSTR WindowName, BSTR FontId, BSTR Text, BOOL Unicode);
summary: Calculates the width of text in a miniwindow
type_of_object: Method
see_also: WindowCreate WindowFontInfo WindowFontList WindowFont WindowText
doc_name: miniwindows
lua_example: width = WindowTextWidth (win, "f", "Lazy dog yawns") -- width of text
description:
This calculates how many pixels a particular piece of text will take up, which can help in calculating how big a window to create, or where to put other things. Note that WindowText returns the number of pixels when it draws text, so you don't need to call WindowTextWidth simply to work out where to draw the very next item.

WindowName - the name of an existing miniwindow.

FontId - a font id that you have loaded.

Text - the text to be calculated (maximum of 8192 characters)

Unicode - if true, the text is Unicode text in UTF-8 format


For more information, see:

http://www.gammon.com.au/mushclient/mw_text.htm

return_value:
If successful, returns the number of pixels the text would take horizontally. 

If unsuccessful, returns a negative number as follows:

-1 : That window name does not exist
-2 : That font was not loaded
-3 : For Unicode, invalid UTF-8 sequence


name: WindowBlendImage
summary: Blends an image into a miniwindow, using a specified blending mode
type_of_object: Method
doc_name: miniwindows
lua_example: WindowBlendImage (win, "im", 0, 0, 0, 0, 1, 0.5) -- mode 1 (normal) at 50% opacity
prototype:
long WindowBlendImage(BSTR WindowName, BSTR ImageId, long Left, long Top, long Right, long Bottom, short Mode, double Opacity, long SrcLeft, long SrcTop, long SrcRight, long SrcBottom);

description:
This blends the specified image into the miniwindow, on top of the specified rectangle.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

ImageId - an image id that you have previously loaded.

Left, Top, Right, Bottom - describes the destination rectangle. The blend image is merged with the contents of this rectangle to produce the blended result.

Mode - the blending method. 

Mode 1 - Normal 
Mode 2 - Average 
Mode 3 - Interpolate 
Mode 4 - Dissolve
Mode 5 - Darken
Mode 6 - Multiply
Mode 7 - Colour Burn
Mode 8 - Linear Burn
Mode 9 - Inverse Colour Burn
Mode 10 - Subtract
Mode 11 - Lighten
Mode 12 - Screen
Mode 13 - Colour Dodge
Mode 14 - Linear Dodge
Mode 15 - Inverse Colour Dodge
Mode 16 - Add
Mode 17 - Overlay
Mode 18 - Soft Light
Mode 19 - Hard Light
Mode 20 - Vivid Light
Mode 21 - Linear Light
Mode 22 - Pin Light
Mode 23 - Hard Mix
Mode 24 - Difference
Mode 25 - Exclusion
Mode 26 - Reflect
Mode 27 - Glow
Mode 28 - Freeze
Mode 29 - Heat
Mode 30 - Negation
Mode 31 - Phoenix
Mode 32 - Stamp
Mode 33 - Xor
Mode 34 - And
Mode 35 - Or
Mode 36 - Red
Mode 37 - Green
Mode 38 - Blue
Mode 39 - Yellow
Mode 40 - Cyan
Mode 41 - Magenta
Mode 42 - Green limited by red
Mode 43 - Green limited by blue
Mode 44 - Green limited by average of red and blue
Mode 45 - Blue limited by red
Mode 46 - Blue limited by green
Mode 47 - Blue limited by average of red and green
Mode 48 - Red limited by green
Mode 49 - Red limited by blue
Mode 50 - Red limited by average of green and blue
Mode 51 - Red only
Mode 52 - Green only
Mode 53 - Blue only
Mode 54 - Discard red
Mode 55 - Discard green
Mode 56 - Discard blue
Mode 57 - All red
Mode 58 - All green
Mode 59 - All blue
Mode 60 - Hue mode
Mode 61 - Saturation mode
Mode 62 - Colour mode
Mode 63 - Luminance mode
Mode 64 - HSL

Opacity - the amount of opacity, between 0 and 1 (floating-point number). An opacity of 0 means you will not see the blend image. An opacity of 1 means the blend is fully applied. An opacity of 0.5 means the blended image is merged 50% with the original contents of the miniwindow.

SrcLeft, SrcTop, SrcRight, SrcBottom - the source rectangle in the original image (use 0,0,0,0 to get the whole image). Negative numbers for the SrcRight and SrcBottom parameters represent an offset from the bottom or right edge.

When blending, whichever rectangle is smaller is the one used for the width and height of the operation (the destination rectangle or the source rectangle).

See also BlendPixel for blending individual pixels.


For more information and screen shots showing the effects of various modes, see:

http://www.gammon.com.au/mushclient/mw_blending.htm

return_value:
eNoSuchWindow - no such miniwindow

eImageNotInstalled - that image was not loaded with WindowLoadImage

eBadParameter - Opacity less than zero or greater than 1.

eOK - completed OK

see_also:
WindowCreate WindowCreateImage WindowDrawImage WindowImageInfo WindowImageOp WindowLoadImage WindowImageList BlendPixel

lua_notes:
In Lua you can use the following constants for the blending modes:

miniwin.blend_normal = 1
miniwin.blend_average = 2
miniwin.blend_interpolate = 3
miniwin.blend_dissolve = 4
miniwin.blend_darken = 5
miniwin.blend_multiply = 6
miniwin.blend_colour_burn = 7
miniwin.blend_linear_burn = 8
miniwin.blend_inverse_colour_burn = 9
miniwin.blend_subtract = 10
miniwin.blend_lighten = 11
miniwin.blend_screen = 12
miniwin.blend_colour_dodge = 13
miniwin.blend_linear_dodge = 14
miniwin.blend_inverse_colour_dodge = 15
miniwin.blend_add = 16
miniwin.blend_overlay = 17
miniwin.blend_soft_light = 18
miniwin.blend_hard_light = 19
miniwin.blend_vivid_light = 20
miniwin.blend_linear_light = 21
miniwin.blend_pin_light = 22
miniwin.blend_hard_mix = 23
miniwin.blend_difference = 24
miniwin.blend_exclusion = 25
miniwin.blend_reflect = 26
miniwin.blend_glow = 27
miniwin.blend_freeze = 28
miniwin.blend_heat = 29
miniwin.blend_negation = 30
miniwin.blend_phoenix = 31
miniwin.blend_stamp = 32
miniwin.blend_xor = 33
miniwin.blend_and = 34
miniwin.blend_or = 35
miniwin.blend_red = 36
miniwin.blend_green = 37
miniwin.blend_blue = 38
miniwin.blend_yellow = 39
miniwin.blend_cyan = 40
miniwin.blend_magenta = 41
miniwin.blend_green_limited_by_red = 42
miniwin.blend_green_limited_by_blue = 43
miniwin.blend_green_limited_by_average_of_red_and_blue = 44
miniwin.blend_blue_limited_by_red = 45
miniwin.blend_blue_limited_by_green = 46
miniwin.blend_blue_limited_by_average_of_red_and_green = 47
miniwin.blend_red_limited_by_green = 48
miniwin.blend_red_limited_by_blue = 49
miniwin.blend_red_limited_by_average_of_green_and_blue = 50
miniwin.blend_red_only = 51
miniwin.blend_green_only = 52
miniwin.blend_blue_only = 53
miniwin.blend_discard_red = 54
miniwin.blend_discard_green = 55
miniwin.blend_discard_blue = 56
miniwin.blend_all_red = 57
miniwin.blend_all_green = 58
miniwin.blend_all_blue = 59
miniwin.blend_hue_mode = 60
miniwin.blend_saturation_mode = 61
miniwin.blend_colour_mode = 62
miniwin.blend_luminance_mode = 63
miniwin.blend_hsl = 64


name: WindowImageFromWindow
prototype: long WindowImageFromWindow(BSTR WindowName, BSTR ImageId, BSTR SourceWindow);
summary: Creates an image from another miniwindow
return_value: eNoSuchWindow - no such miniwindow (either source or destination) eOK - completed OK
type_of_object: Method
doc_name: miniwindows
description:
This uses an existing miniwindow's offscreen bitmap, to make an image that can be loaded into another miniwindow. This lets you set up offscreen windows (that you may never plan to actually show with WindowShow) as "work areas" for creating text or images, that can be loaded or blended into other windows.

WindowName - the name of an existing miniwindow.

ImageId - the image id to store its image under.

SourceWindow - the miniwindow name that is the source of the image.


For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

see_also:
WindowCreate WindowCreateImage WindowDrawImage WindowImageInfo WindowImageOp WindowLoadImage WindowImageList

lua_example:
-- create another window
WindowCreate ("map2window", 0, 0, 150, 150, 4, 0, 0x000000) ) -- top left corner

-- pull in map window as "map" from mapping plugin 
WindowImageFromWindow("map2window", "map", "86810b755a33169f0f1d9585")

-- draw our small map into "map2" window
WindowDrawImage ("map2window", "map", 0, 0, 0, 0, 2);

-- show smaller map
WindowShow ("map2window", true)


name: WindowGradient
summary: Draws a gradient in a rectangle
type_of_object: Method
doc_name: miniwindows
prototype:
long WindowGradient(BSTR WindowName, long Left, long Top, long Right, long Bottom, long StartColour, long EndColour, short Mode);

description:
Draws a gradient - that is a rectangle that gradually changes from the start colour to the end colour.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

Left, Top, Right, Bottom - describes the rectangle to draw into.

StartColour - the colour to start the gradient (or, see below if you are using Mode 3)

EndColour - the colour to end the gradient.

Mode - the drawing direction. One of:

1 - horizontal - left to right

2 - vertical - top to bottom

3 - make a texture by xoring the x and y columns sequentially.

For Mode 3 (make a texture) - the StartColour has 3 components, red multiplier, green multiplier, blue multiplier. These are multiplied by the generated colour to give special effects to the generated texture. For example: 0x010203 would multiply the blue component by 1, the green component by 2 and the red component by 3.


For more information, see:

http://www.gammon.com.au/mushclient/mw_shapes.htm

return_value:
eNoSuchWindow - no such miniwindow (either source or destination)

eUnknownOption - mode not one of the modes specified above

eOK - completed OK

see_also:
WindowCreate WindowCreateImage WindowDrawImage WindowImageInfo WindowImageOp WindowLoadImage WindowImageList

lua_example:
WindowGradient (win, 20, 110, 160, 180, 
                ColourNameToRGB ("red"), 
                ColourNameToRGB ("yellow"), 
                1)  -- left to right

WindowGradient (win, 20, 20, 160, 100, 
                ColourNameToRGB ("dodgerblue"), 
                ColourNameToRGB ("lightsalmon"), 
                2)  -- top to bottom

WindowGradient (win, 0, 0, 256, 256, 
                0x010203, 
                0,
                3)  -- XOR texture

lua_notes:
You can use the following constants for the mode:

miniwin.gradient_horizontal = 1
miniwin.gradient_vertical = 2
miniwin.gradient_texture = 3


name: Repaint
prototype: void Repaint();
summary: Forces an immediate redraw for all windows for this world
vb_example: Repaint
java_example: Repaint();
perl_example: $world-> Repaint();
return_value: Nothing.
type_of_object: Method
see_also: NormalColour BoldColour NoteColour CustomColourBackground CustomColourText Redraw
python_example: Repaint
lua_example: Repaint ()
description:
This function forces the output window to be redrawn. This should not normally be called, as the window will be redrawn at the appropriate time through the main "event loop". 

Unnecessary calls to Repaint will slow the program down. 

However for "animation" situations (like moving an image over a map) there may be times when you actually want the window redrawn, between "frames". In this case, you could call Repaint to force an immediate redraw.

Otherwise, use Redraw instead, which will cause the window to be redrawn at the next appropriate opportunity.


name: TextRectangle
summary: Specifies the size of the rectangle in which text is displayed in the output window.
return_value: eBrushStyleNotValid - invalid brush style specified for OutsideFillStyle eOK - done OK
type_of_object: Method
see_also: Redraw Repaint
doc_name: miniwindows
prototype:
long TextRectangle(long Left, long Top, long Right, long Bottom, long BorderOffset, long BorderColour, long BorderWidth, long OutsideFillColour, long OutsideFillStyle);

description:
This reduces the rectangle in which normal MUD output is displayed, from the entire output window, to the subset specified. 

This can be used to make a "desktop effect" where you have room on all sides for miniwindows to be placed. 

A border can be drawn at the edge of the rectangle to make it obvious where the text ends, to help in resizing the window. 

The text is clipped to be within the text rectangle. A window redraw is forced.

Left, Top, Right, Bottom - describes the rectangle in which the text is drawn. If 0,0,0,0 is specified, text is drawn "normally" to the borders of the output window.

BorderOffset - the offset in pixels between the edge of the text, and the border. You can specify a few pixels here so that the text is not jammed up against the border.

BorderColour - the colour to draw the border in (RGB value).

BorderWidth - the width of the border - make zero for no border.

OutsideFillColour - the brush colour to fill the area outside the text rectangle.

OutsideFillStyle - the brush mode to use for the outside fill. See Brush parameters for a description of the various modes. The brush modes can be:

0: solid (filled with a solid colour)
1: null (not filled)
2: hatch: horizontal
3: hatch: vertical
4: hatch: forwards diagonal
5: hatch: backwards diagonal
6: hatch: cross
7: hatch: diagonal cross
8: fine pattern
9: medium pattern
10: coarse pattern
11: waves - horizontal
12: waves - vertical

lua_example:
TextRectangle(50,   -- left
              100,  -- top
              50 + GetInfo (213) * 80, -- 50 + width for 80 characters
              -100,  -- 100 pixels from the bottom
              5,  -- BorderOffset, 
              ColourNameToRGB ("gray"),    -- BorderColour, 
              2,  -- BorderWidth, 
              ColourNameToRGB ("silver"),  -- OutsideFillColour, 
              8) -- OutsideFillStyle (fine hatch)

lua_notes:
You can use the following constants for the outside fill style:

miniwin.brush_solid = 0
miniwin.brush_null = 1
miniwin.brush_hatch_horizontal = 2
miniwin.brush_hatch_vertical = 3
miniwin.brush_hatch_forwards_diagonal = 4
miniwin.brush_hatch_backwards_diagonal = 5
miniwin.brush_hatch_cross = 6
miniwin.brush_hatch_cross_diagonal = 7
miniwin.brush_fine_pattern = 8
miniwin.brush_medium_pattern = 9
miniwin.brush_coarse_pattern = 10
miniwin.brush_waves_horizontal = 11
miniwin.brush_waves_vertical = 12


name: WindowFilter
summary: Performs a filtering operation over part of the miniwindow.
type_of_object: Method
see_also: WindowCreate WindowImageList WindowDrawImage WindowImageInfo WindowCreateImage FilterPixel
doc_name: miniwindows
prototype:
long WindowFilter(BSTR WindowName, long Left, long Top, long Right, long Bottom, short Operation, double Options);

description:
This takes a copy of the specified rectangle in a miniwindow, filters it according to the operation specified, and replaces the filtered version back in place. 

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow. 

Left, Top, Right, Bottom - describes the rectangle to be filtered. 

Operation - the filter operation. At present, one of: 

1 - Apply colour noise 

2 - Apply monochrome noise 

3 - Blur (by comparing 2 pixels on each side)

4 - Sharpen 

5 - Find edges 

6 - Emboss 

7 - Adjust Brightness (by adding Options to each pixel)

8 - Adjust Contrast 

9 - Adjust Gamma 

10 - Adjust Brightness for red channel only  (by adding Options to each pixel)

11 - Adjust Contrast for red channel only 

12 - Adjust Gamma for red channel only 

13 - Adjust Brightness for green channel only  (by adding Options to each pixel)

14 - Adjust Contrast for green channel only 

15 - Adjust Gamma for green channel only 

16 - Adjust Brightness for blue channel only  (by adding Options to each pixel)

17 - Adjust Contrast for blue channel only 

18 - Adjust Gamma for blue channel only 

19 - Convert to grayscale - mix red/green/blue equally 

20 - Convert to grayscale - mix 30% red + 59% green + 11% blue for normal perception 

21 - Adjust Brightness (by multiplying Options by each pixel)

22 - Adjust Brightness for red channel only  (by multiplying Options by each pixel)

23 - Adjust Brightness for green channel only   (by multiplying Options by each pixel)

24 - Adjust Brightness for blue channel only   (by multiplying Options by each pixel)

25 - Lesser Blur (by comparing 1 pixel on each side)

26 - Minor Blur (by comparing 1 pixel on each side, taking a smaller amount)

27 - Average - the entire rectangle is set to its average colour


Single channel operations - the modes which specify a single channel (10 to 18, 22 to 24) operate on that colour channel only (red, green or blue) leaving the others untouched. Thus by, say, increasing brightness on the red channel you add to the red pixels, but leave green and blue alone, making the image look redder. However decreasing brightness on the red channel would make the image look more cyan (as cyan is the complementary colour to red).

The complementary colours are:

red / cyan 
green / magenta 
blue / yellow 



Options - filtering options. 


For the Noise filter: 

A number from about 0 to 255 indicating how much noise to add. 


For the Blur, Sharpen, Find Edges and Emboss filters: 

0 - both directions 
1 - horizontal only 
2 - vertical only 


For the Brightness (additive) filter: 

A number from -255 to +255 to indicate the amount to increase (or decrease) the value of each pixel - by adding. A negative number will make it darker, a positive number will make it brighter. 


For the Brightness (multiplicative) filter: 

A number which is multiplied by the value of each pixel. A number less than 1 will make it darker, a number greater than 1 will make it brighter. However black (zero) will remain black.


For the Contrast filter: 

A number to indicate the amount to multiply by the value of each pixel. Zero will make the picture zero contrast, that is totally grey. If you use 1 the pixel will be normal contrast (as each pixel is multiplied by 1). A value between 0 and 1 will be lower contrast. A value above 1 will increase contrast. Negative numbers will have the effect of making the image look negative. 


For the Gamma filter: 

A number to indicate the amount of Gamma adjustment. Mathematically each pixel is raised to the power of this number. Thus, a gamma of 1 will result in no change. A gamma of 2 will darken the image somewhat. A gamma of 0.5 will lighten the image. A gamma of zero will make the image totally white. 
The difference between gamma and brightness is that increasing brightness simply adds to the value of each pixel, so that black becomes gray, and bright pixel become clipped. Similarly, decreasing brightness means that white pixels become grey, and dark ones are clipped. 

However because gamma is a power function, black stays black, and white stays white, with the biggest change in the mid range. A higher gamma value results in a darker image with more contrast. A lower gamma value (between 0 and 1) results in a lighter image with less contrast. 


Warning - filtering is quite computation-expensive. For example, for a 600 x 600 pixel image, the program has to apply a calculation to 600 x 600 x 3 bytes (one for each of red, green and blue), which would be 1,080,000 calculations. In addition, most of the filtering operations (except noise) need to do a calculation on a "window" of adjoining pixels (2 on each side of each pixel), effectively multiplying the number of calculations by a further 5. 

If possible, apply a filter once, and use the filtered image many times. As you can use miniwindows as image sources for other miniwindows, consider setting up a filtered image once, and then just copying it in when needed (eg. draw an elaborate background once, and then just copy in the result when needed). 

See also FilterPixel which filters a single RGB code.

For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

return_value:
eNoSuchWindow - no such miniwindow

eUnknownOption - filter mode not in the list above

eOK - completed OK

lua_example:
-- Noise

WindowFilter (win, 0, 0, 0, 0, 1, 100)  -- colour noise in whole window - level 100
WindowFilter (win, 0, 0, 0, 0, 1, 50)   -- colour noise in whole window - level 50
WindowFilter (win, 0, 0, 0, 0, 2, 100)  -- monochrome noise in whole window - level 100


-- Blurring

WindowFilter (win, 10, 10, 90, 90, 3, 0) -- blur both directions
WindowFilter (win, 10, 10, 90, 90, 3, 1) -- blur horizontal
WindowFilter (win, 10, 10, 90, 90, 3, 2) -- blur vertical


-- Sharpening

WindowFilter (win, 10, 10, 90, 90, 4, 0) -- sharpen in both directions


-- Edge detection

WindowFilter (win, 10, 10, 90, 90, 5, 0) -- edge detect


-- Emboss

WindowFilter (win, 10, 10, 90, 90, 6, 0) -- emboss


-- Brightness

WindowFilter (win, 10, 10, 90, 90, 7, -100) -- lower by 100
WindowFilter (win, 10, 10, 90, 90, 7, 100) -- raise by 100

WindowFilter (win, 10, 10, 90, 90, 21, 0.5) -- halve the brightness
WindowFilter (win, 10, 10, 90, 90, 21, 2) -- double the brightness


-- Contrast

WindowFilter (win, 10, 10, 90, 90, 8, 0.5) -- reduce
WindowFilter (win, 10, 10, 90, 90, 8, 2) -- increase
WindowFilter (win, 10, 10, 90, 90, 8, 10) -- increase a lot
WindowFilter (win, 10, 10, 90, 90, 8, -2) -- make negative


-- Gamma

WindowFilter (win, 10, 10, 90, 90, 9, 0.3) -- brighter, lower contrast
WindowFilter (win, 10, 10, 90, 90, 9, 1.5)  -- darker, higher contrast
WindowFilter (win, 10, 10, 90, 90, 9, 5)   -- very dark and contrasty

lua_notes:
You can use the following constants for the Operation argument:

miniwin.filter_noise = 1
miniwin.filter_monochrome_noise = 2
miniwin.filter_blur = 3
miniwin.filter_sharpen = 4
miniwin.filter_find_edges = 5
miniwin.filter_emboss = 6
miniwin.filter_brightness = 7
miniwin.filter_contrast = 8
miniwin.filter_gamma = 9
miniwin.filter_red_brightness = 10
miniwin.filter_red_contrast = 11
miniwin.filter_red_gamma = 12
miniwin.filter_green_brightness = 13
miniwin.filter_green_contrast = 14
miniwin.filter_green_gamma = 15
miniwin.filter_blue_brightness = 16
miniwin.filter_blue_contrast = 17
miniwin.filter_blue_gamma = 18
miniwin.filter_grayscale = 19
miniwin.filter_normal_grayscale = 20
miniwin.filter_brightness_multiply = 21
miniwin.filter_red_brightness_multiply = 22
miniwin.filter_green_brightness_multiply = 23
miniwin.filter_blue_brightness_multiply = 24
miniwin.filter_lesser_blur = 25
miniwin.filter_minor_blur = 26
miniwin.filter_average = 27


name: SetBackgroundImage
prototype: long SetBackgroundImage(BSTR FileName, short Mode);
summary: Sets a background image for the output window
type_of_object: Method
see_also: SetBackgroundColour SetForegroundImage
doc_name: utils
lua_example: SetBackgroundImage ("wolf.bmp", 0)
description:
This sets a background image for output window. The text in the output window is drawn on top of this. If the image does not completely fill the window, the background colour is visible beneath it. 

FileName - the disk file to load the image from. It should be a BMP or PNG file, not a GIF, TIF or other file type.  The file name can be the empty string (ie. "") in which case any existing image will be removed.

Mode - a number indicating where you want the image positioned on the screen. Whenever the screen is resized or redrawn the contents of the image are drawn in the requested position: 

0 = strech to output view size 
1 = stretch with aspect ratio 
2 = strech to owner size 
3 = stretch with aspect ratio 
4 = top left 
5 = center left-right at top 
6 = top right 
7 = on right, center top-bottom 
8 = on right, at bottom 
9 = center left-right at bottom 
10 = on left, at bottom 
11 = on left, center top-bottom 
12 = centre all 
13 = tile 

The "stretch" versions expand or contract the image to fit the output window. If you use "with aspect ratio" the image fits exactly top-to-bottom, and may be clipped left-right to preserve the original aspect ratio. 

The difference beteween "output view" and "owner size" is that with "output view" (modes 0 and 1) the image will tend to flicker annoyingly if you have automatic resizing of the command window active (as this will make the output window size change, and thus the image size will keep changing) .

return_value:
eBadParameter: Mode out of range above, or file name less than 5 characters, or file name does not end in .BMP or .PNG

eFileNotFound: File not found

eCouldNotOpenFile: File could not be loaded (perhaps corrupt)

eOK: Success

lua_notes:
You can use the following constants for the position:

miniwin.pos_stretch_to_view = 0
miniwin.pos_stretch_to_view_with_aspect = 1
miniwin.pos_stretch_to_owner = 2
miniwin.pos_stretch_to_owner_with_aspect = 3
miniwin.pos_top_left = 4
miniwin.pos_top_center = 5
miniwin.pos_top_right = 6
miniwin.pos_center_right = 7
miniwin.pos_bottom_right = 8
miniwin.pos_bottom_center = 9
miniwin.pos_bottom_left = 10
miniwin.pos_center_left = 11
miniwin.pos_center_all = 12
miniwin.pos_tile = 13


name: SetForegroundImage
prototype: long SetForegroundImage(BSTR FileName, short Mode);
summary: Sets a foreground image for the output window
type_of_object: Method
see_also: SetBackgroundColour SetBackgroundImage
doc_name: utils
lua_example: SetForegroundImage ("wolf.bmp", 0)
description:
This sets a foreground image for output window. The text in the output window is drawn under this.  

With "stretching" or "tiling" modes, the text from the MUD will not be visible.

FileName - the disk file to load the image from. It should be a BMP or PNG file, not a GIF, TIF or other file type. The file name can be the empty string (ie. "") in which case any existing image will be removed.

Mode - a number indicating where you want the image positioned on the screen. Whenever the screen is resized or redrawn the contents of the image are drawn in the requested position: 

0 = strech to output view size 
1 = stretch with aspect ratio 
2 = strech to owner size 
3 = stretch with aspect ratio 
4 = top left 
5 = center left-right at top 
6 = top right 
7 = on right, center top-bottom 
8 = on right, at bottom 
9 = center left-right at bottom 
10 = on left, at bottom 
11 = on left, center top-bottom 
12 = centre all 
13 = tile 

The "stretch" versions expand or contract the image to fit the output window. If you use "with aspect ratio" the image fits exactly top-to-bottom, and may be clipped left-right to preserve the original aspect ratio. 

The difference beteween "output view" and "owner size" is that with "output view" (modes 0 and 1) the image will tend to flicker annoyingly if you have automatic resizing of the command window active (as this will make the output window size change, and thus the image size will keep changing) .

return_value:
eBadParameter: Mode out of range above, or file name less than 5 characters, or file name does not end in .BMP or .PNG

eFileNotFound: File not found

eCouldNotOpenFile: File could not be loaded (perhaps corrupt)

eOK: Success

lua_notes:
You can use the following constants for the position:

miniwin.pos_stretch_to_view = 0
miniwin.pos_stretch_to_view_with_aspect = 1
miniwin.pos_stretch_to_owner = 2
miniwin.pos_stretch_to_owner_with_aspect = 3
miniwin.pos_top_left = 4
miniwin.pos_top_center = 5
miniwin.pos_top_right = 6
miniwin.pos_center_right = 7
miniwin.pos_bottom_right = 8
miniwin.pos_bottom_center = 9
miniwin.pos_bottom_left = 10
miniwin.pos_center_left = 11
miniwin.pos_center_all = 12
miniwin.pos_tile = 13


name: SetBackgroundColour
prototype: long SetBackgroundColour(long Colour);
summary: Sets a background colour for the output window
return_value: The RGB colour which was the previous background colour.
type_of_object: Method
see_also: SetForegroundImage SetBackgroundImage
doc_name: utils
lua_example: SetBackgroundColour (0x000055)
description:
This changes the default background colour of the output window. This is intended to be used to make "mood" changes to the output window. For example, if you are currently playing in a watery zone, the background colour could change from black to a deep blue. 

You simply specify the RGB code for the desired colour, or the constant 0xFFFFFFFF to indicate to use the default behaviour. Normally MUSHclient draws the background in ANSI colour "normal black". If you have set a colour, then any time the background colour for text would have been "normal black", then the background is not drawn and thus the background colour you chose is allowed to stay. 

This function cannot fail, and returns the previous background colour.


name: WindowSetPixel
prototype: long WindowSetPixel(BSTR WindowName, long x, long y, long Colour);
summary: Sets a single pixel in a miniwindow to the specified colour
return_value: eNoSuchWindow - no such miniwindow eOK - success
type_of_object: Method
doc_name: miniwindows
description:
Sets a single pixel in the miniwindow. 

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow. 

x, y - the location of the pixel (x is horizontal, y is vertical)

Colour - the colour to set the pixel to. Note that the pixel which appears in the window may not necessarily be the exact one you chose, depending on the colour depth of your monitor. For example, for 16-bit colour depth, only 5 bits are used for each of red/green/blue, and thus a colour that cannot be exactly expressed in 5 bits will be rounded to the nearest colour.


Warning - although setting individual pixels is reasonably fast, if you need to set a lot (for example, to draw a line or a box), it would be much faster to use the appropriate dedicated function (such as WindowLine). This is because to draw boxes and lines, especially large ones, or filled ones, would take many, many calls to WindowSetPixel to achieve the same result.

see_also:
WindowArc WindowBezier WindowCreate WindowDrawImage WindowCircleOp WindowLine WindowRectOp WindowPolygon WindowGetPixel

lua_example:
for x = 1, 360 do
  local y = math.sin (math.rad (x)) * 100
  WindowSetPixel (win, x, y + 120, 0xFF0000)
end -- for


name: WindowGetPixel
prototype: long WindowGetPixel(BSTR WindowName, long x, long y);
summary: Gets the colour of a single pixel in a miniwindow
type_of_object: Method
doc_name: miniwindows
lua_example: c = WindowGetPixel (win, 2, 3)
description:
Gets a single pixel colour from the miniwindow. 

WindowName - the name of an existing miniwindow. 

x, y - the location of the pixel (x is horizontal, y is vertical)


Note that after doing a WindowSetPixel, if you do a WindowGetPixel you will not necessarily get back the same value, particularly if the screen monitor resolution is set to 16 bit colour or less.

return_value:
-1 if the pixel is out of the range of the window size.

-2 if the miniwindow does not exist.

Otherwise: The colour at that location as an RGB code.

see_also:
WindowArc WindowBezier WindowCreate WindowDrawImage WindowCircleOp WindowLine WindowRectOp WindowPolygon WindowSetPixel


name: WindowWrite
prototype: long WindowWrite(BSTR WindowName, BSTR FileName);
summary: Writes the contents of a miniwindow to disk as a graphics file
type_of_object: Method
see_also: WindowLoadImage
doc_name: miniwindows
lua_example: WindowWrite (win, "window_saved.png");
description:
The entire contents of the named miniwindow are written to disk as file name FileName. The file name must end in .PNG or .BMP.   Based on the file name, either a BMP or PNG file is written.

The file name is not case-sensitive.

return_value:
eNoSuchWindow - no such miniwindow

eNoNameSpecified - no file name specified

eBadParameter - file name too short or does not end in .BMP or .PNG

eCouldNotOpenFile - cannot open file (eg. pathname does not exist, no write permissions)

eLogFileBadWrite - problem writing (eg. disk full)

eOK - success


name: FilterPixel
prototype: long FilterPixel(long Pixel, short Operation, double Options);
summary: Performs a filtering operation on one pixel
return_value: -1 : filter mode not in the list above. Otherwise, the filtered pixel as an RGB code
type_of_object: Method
see_also: WindowFilter
doc_name: utils
description:
This applies the specified filtering operation to the pixel supplied (an RGB code).

This does largely the same thing as WindowFilter, except it operates on a single pixel (that is, a single RGB colour). This does the same operations (with the same codes as for WindowFilter) excepting the ones which require more than one pixel (like Blur, Sharpen, Find Edges, and Emboss).


Operation - the filter operation. At present, one of: 

1 - Apply colour noise 

2 - Apply monochrome noise 

7 - Adjust Brightness (by adding Options to the pixel)

8 - Adjust Contrast 

9 - Adjust Gamma 

10 - Adjust Brightness for red channel only  (by adding Options to the pixel)

11 - Adjust Contrast for red channel only 

12 - Adjust Gamma for red channel only 

13 - Adjust Brightness for green channel only  (by adding Options to the pixel)

14 - Adjust Contrast for green channel only 

15 - Adjust Gamma for green channel only 

16 - Adjust Brightness for blue channel only  (by adding Options to the pixel)

17 - Adjust Contrast for blue channel only 

18 - Adjust Gamma for blue channel only 

19 - Convert to grayscale - mix red/green/blue equally 

20 - Convert to grayscale - mix 30% red + 59% green + 11% blue for normal perception 

21 - Adjust Brightness (by multiplying Options by the pixel)

22 - Adjust Brightness for red channel only  (by multiplying Options by the pixel)

23 - Adjust Brightness for green channel only   (by multiplying Options by the pixel)

24 - Adjust Brightness for blue channel only   (by multiplying Options by the pixel)

27 - Average - the pixel's average colour (that is, itself)


Single channel operations - the modes which specify a single channel (10 to 18, 22 to 24) operate on that colour channel only (red, green or blue) leaving the others untouched. Thus by, say, increasing brightness on the red channel you add to the red value, but leave green and blue alone, making the image look redder. However decreasing brightness on the red channel would make the image look more cyan (as cyan is the complementary colour to red).

The complementary colours are:

red / cyan 
green / magenta 
blue / yellow 



Options - filtering options. 


For the Noise filter: 

A number from about 0 to 255 indicating how much noise to add. 


For the Brightness (additive) filter: 

A number from -255 to +255 to indicate the amount to increase (or decrease) the value of the pixel - by adding. A negative number will make it darker, a positive number will make it brighter. 


For the Brightness (multiplicative) filter: 

A number which is multiplied by the value of the pixel. A number less than 1 will make it darker, a number greater than 1 will make it brighter. However black (zero) will remain black.


For the Contrast filter: 

A number to indicate the amount to multiply by the value of the pixel. Zero will make the picture zero contrast, that is totally grey. If you use 1 the pixel will be normal contrast (as each pixel is multiplied by 1). A value between 0 and 1 will be lower contrast. A value above 1 will increase contrast. Negative numbers will have the effect of making the image look negative. 


For the Gamma filter: 

A number to indicate the amount of Gamma adjustment. Mathematically the pixel is raised to the power of this number. Thus, a gamma of 1 will result in no change. A gamma of 2 will darken the image somewhat. A gamma of 0.5 will lighten the image. A gamma of zero will make the image totally white. 
The difference between gamma and brightness is that increasing brightness simply adds to the value of each pixel, so that black becomes gray, and bright pixel become clipped. Similarly, decreasing brightness means that white pixels become grey, and dark ones are clipped. 

However because gamma is a power function, black stays black, and white stays white, with the biggest change in the mid range. A higher gamma value results in a darker image with more contrast. A lower gamma value (between 0 and 1) results in a lighter image with less contrast. 


For more information, see:

http://www.gammon.com.au/mushclient/mw_images.htm

lua_example:
-- Brightness

FilterPixel (0x445566, 7, -4) -- lower by 4 (gives 0x405162)
FilterPixel (0x445566, 7, 10) -- raise by 10 (gives 0x4e5f70)

FilterPixel (0x445566, 21, 0.5) -- halve the brightness (gives 0x222a33)
FilterPixel (0x445566, 21, 2) -- double the brightness (gives 0x88aacc)


-- Contrast

FilterPixel (0x445566, 8, 0.5) -- reduce (gives 0x626a73)
FilterPixel (0x445566, 8, 2) -- increase (gives 0x082a4c)


-- Gamma

FilterPixel (0x445566, 9, 0.3) -- brighter, lower contrast (gives 0xabb7c1)
FilterPixel (0x445566, 9, 1.5) -- darker, higher contrast (gives 0x233140)
FilterPixel (0x445566, 9, 5)   -- very dark and contrasty (gives 0x000102)

lua_notes:
You can use the following constants for the Operation argument:

miniwin.filter_noise = 1
miniwin.filter_monochrome_noise = 2
miniwin.filter_brightness = 7
miniwin.filter_contrast = 8
miniwin.filter_gamma = 9
miniwin.filter_red_brightness = 10
miniwin.filter_red_contrast = 11
miniwin.filter_red_gamma = 12
miniwin.filter_green_brightness = 13
miniwin.filter_green_contrast = 14
miniwin.filter_green_gamma = 15
miniwin.filter_blue_brightness = 16
miniwin.filter_blue_contrast = 17
miniwin.filter_blue_gamma = 18
miniwin.filter_grayscale = 19
miniwin.filter_normal_grayscale = 20
miniwin.filter_brightness_multiply = 21
miniwin.filter_red_brightness_multiply = 22
miniwin.filter_green_brightness_multiply = 23
miniwin.filter_blue_brightness_multiply = 24
miniwin.filter_average = 27


name: BlendPixel
prototype: long BlendPixel(long Blend, long Base, short Mode, double Opacity);
summary: Blends a single pixel with another, using a specified blending mode
type_of_object: Method
see_also: WindowBlendImage
doc_name: utils
lua_example: BlendPixel (0x123456, 0x445566, 1, 0.5) -- mode 1 (normal) at 50% opacity (gives 0x2b445e)
description:
This does the same thing as WindowBlendImage, except it operates on a single pixel (that is, a single RGB colour for the blend colour, and a single RGB colour for the base colour). This does the same thing, to a single pixel, as WindowBlendImage (with the same codes). This is intended for situations where you need to work on individual colours - either in a miniwindow image, or generally, to do things like merge them together in various ways.

Blend - the RGB code of the pixel to be blended

Base - the RGB code of the base pixel

Mode - the blending method. 

Mode 1 - Normal 
Mode 2 - Average 
Mode 3 - Interpolate 
Mode 4 - Dissolve
Mode 5 - Darken
Mode 6 - Multiply
Mode 7 - Colour Burn
Mode 8 - Linear Burn
Mode 9 - Inverse Colour Burn
Mode 10 - Subtract
Mode 11 - Lighten
Mode 12 - Screen
Mode 13 - Colour Dodge
Mode 14 - Linear Dodge
Mode 15 - Inverse Colour Dodge
Mode 16 - Add
Mode 17 - Overlay
Mode 18 - Soft Light
Mode 19 - Hard Light
Mode 20 - Vivid Light
Mode 21 - Linear Light
Mode 22 - Pin Light
Mode 23 - Hard Mix
Mode 24 - Difference
Mode 25 - Exclusion
Mode 26 - Reflect
Mode 27 - Glow
Mode 28 - Freeze
Mode 29 - Heat
Mode 30 - Negation
Mode 31 - Phoenix
Mode 32 - Stamp
Mode 33 - Xor
Mode 34 - And
Mode 35 - Or
Mode 36 - Red
Mode 37 - Green
Mode 38 - Blue
Mode 39 - Yellow
Mode 40 - Cyan
Mode 41 - Magenta
Mode 42 - Green limited by red
Mode 43 - Green limited by blue
Mode 44 - Green limited by average of red and blue
Mode 45 - Blue limited by red
Mode 46 - Blue limited by green
Mode 47 - Blue limited by average of red and green
Mode 48 - Red limited by green
Mode 49 - Red limited by blue
Mode 50 - Red limited by average of green and blue
Mode 51 - Red only
Mode 52 - Green only
Mode 53 - Blue only
Mode 54 - Discard red
Mode 55 - Discard green
Mode 56 - Discard blue
Mode 57 - All red
Mode 58 - All green
Mode 59 - All blue
Mode 60 - Hue mode
Mode 61 - Saturation mode
Mode 62 - Colour mode
Mode 63 - Luminance mode
Mode 64 - HSL

Opacity - the amount of opacity, between 0 and 1 (floating-point number). An opacity of 0 means the result will be the base pixel. An opacity of 1 means the blend is fully applied. An opacity of 0.5 means the blended pixel is merged 50% with the original pixel.


For more information and screen shots showing the effects of various modes, see:

http://www.gammon.com.au/mushclient/mw_blending.htm

return_value:
-1: The blend mode was not in the above list.

-2: Opacity less than zero or greater than 1.

Otherwise, the RGB code resulting from the blend operation.


name: WindowMergeImageAlpha
summary: Merges an image into a miniwindow based on an alpha mask
type_of_object: Method
see_also: WindowBlendImage WindowLoadImage WindowGetImageAlpha
doc_name: miniwindows
prototype:
long WindowMergeImageAlpha(BSTR WindowName, BSTR ImageId, BSTR MaskId, long Left, long Top, long Right, long Bottom, short Mode, double Opacity, long SrcLeft, long SrcTop, long SrcRight, long SrcBottom);

description:
This merges the previously-loaded image identified by ImageId onto the miniwindow, based on the opacity of the mask MaskId. The mask must be large enough to cover the requested area in the blended image.

One method of setting up a mask would be to use the WindowGetImageAlpha function to obtain the alpha information from an image. Alternatively you might have the alpha information in a separate image file.

Each colour (red/green/blue) in the mask is individually considered when merging each pixel. If the mask is white (ie. 255) for that colour, then the blended image is used. If the mask is black (ie. 0) then the base image is preserved. In between, the blended image is used to the extent of the value (for example, 128 would be a 50% blend).

You can use a mask with a soft border (eg. by blurring it) to make a soft transition between the loaded image and the existing contents of the miniwindow.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

ImageId - an image id that you have previously loaded.

MaskId - an image id for the mask, which has been previously loaded.

Left, Top, Right, Bottom - describes the destination rectangle. The blend image is merged with the contents of this rectangle to produce the blended result.

Mode - the blending method. 

0 = straight blend
1 = transparent blend - the pixel at 0,0 in the ImageId image will be taken as the transparency colour.

Opacity - the amount of opacity, between 0 and 1 (floating-point number). An opacity of 0 means you will not see the merged image. An opacity of 1 means the merge is fully applied. An opacity of 0.5 means the masked, merged image is merged 50% with the original contents of the miniwindow.

SrcLeft, SrcTop, SrcRight, SrcBottom - the source rectangle in the original image (use 0,0,0,0 to get the whole image). Negative numbers for the SrcRight and SrcBottom parameters represent an offset from the bottom or right edge.

When blending, whichever rectangle is smaller is the one used for the width and height of the operation (the destination rectangle or the source rectangle).

return_value:
eBadParameter - Opacity not in range 0 to 1, or mask not large enough

eImageNotInstalled - Either the blend image or the mask image is not installed

eNoSuchWindow - No such miniwindow

eUnknownOption - Mode not in list above

eOK - success

lua_example:
WindowMergeImageAlpha (win, "castle", "mask", 
                       0, 0, 0, 0,   -- full image
                       1, 1,            -- use transparency, 100% opacity
                       0, 0, 0, 0)  -- source offset

lua_notes:
You can use the following constants for the mode:

miniwin.merge_straight = 0
miniwin.merge_transparent = 1


name: WindowDelete
prototype: long WindowDelete(BSTR WindowName);
summary: Deletes a miniwindow
return_value: eNoSuchWindow - there is no such miniwindow eOK - success
type_of_object: Method
see_also: WindowInfo WindowList WindowShow WindowCreate
doc_name: miniwindows
lua_example: WindowDelete (win)
description:
This deletes an existing miniwindow, freeing all the resources it used.

WindowName - the name of the existing miniwindow.


This forces a redraw of the output window, so the window is removed from the screen, if necessary.


name: WindowMenu
prototype: BSTR WindowMenu(BSTR WindowName, long Left, long Top, BSTR Items);
summary: Creates a pop-up menu inside a miniwindow
type_of_object: Method
see_also: WindowInfo WindowList WindowShow WindowDelete Menu
doc_name: miniwindows
description:
This creates a pop-up menu inside a miniwindow. This is intended to let you click on an item (for example, a piece of inventory), and select "take/drop/equip/wield" and so on.

The window must exist, and be visible, or an empty string is returned.


WindowName: The name of an existing miniwindow

Left: The X position inside the miniwindow

Top: The Y position inside the miniwindow

Items: A string containing the menu items to be displayed, see below.


The X and Y position must be inside the miniwindow (ie. not negative, and not exceeding the miniwindow's defined width and height). Otherwise, an empty string is returned.

You can use WindowInfo (win, 14) and WindowInfo (win, 15) to find where the mouse was last clicked inside this miniwindow.

The Items parameter is a string, containing the menu items to be displayed, separated by the "|" character. Leading and trailing spaces are removed from each item.

For example:  Item = "^Sword | - | Wield | Equip | - |  Take | Drop "

There must be at least one item,  or an empty string is returned.

An item which is empty, or consisting of the character "-" is displayed as a menu separator (horizontal line).

An item which commences with the "^" character is displayed disabled (grayed out, and it cannot be selected). The "^" character is removed.

An item which commences with the "+" character is displayed checked (with a tick mark next to it). The "+" character is removed.

Items may have both a + and ^ in front of them, in either order.

An item which commences with the ">" character represents a nested menu. Subsequent items until a "<" character are in the nested menu.

An item which commences with the "<" character ends a nested menu.

You can display a maximum of 100 selectable items. This does not count nested menus items, disabled items, and separator lines. That is, there can be a maximum of 100 items which can be actually chosen by the player.

The return value is the selected item, if any. If no item is selected (ie. the menu is dismissed) then an empty string will be returned.

In the above example, a menu would be shown like this:

Sword (grayed out)
-----
Wield
Equip
-----
Take
Drop

Thus the return value would be one of:

"" - menu dismissed
"Wield", "Equip", "Take", or "Drop"

Note that the leading and trailing spaces around the items have been removed in the return value.

WARNING - we reserve non alpha-numeric characters in the first position of each item for future expansion. For example, perhaps in future versions "*Equip" might be used to tick the Equip item.

SUGGESTION - we strongly recommend that, if you are creating a menu in response to a mouse-click, you do it on the "mouse up" rather than "mouse down".

The reason for this is that MUSHclient tracks mouse-down events and their corresponding mouse-up events, in order to call the appropriate hotspot routines (mouse-down, mouse-up, mouse-down cancel). 

However if you call WindowMenu in response to a mouse-down, the next mouse-up is "swallowed" up by the menu handler, and thus MUSHclient doesn't "see" it. The end result is that MUSHclient thinks the mouse is down, when it is in fact up. This gets the hotspot events out of synchronization, and then subsequent things like mouse-overs are not processed correctly.

So, for best results, draw a menu after a mouse-up. This if in fact what most Windows programs do, if you look carefully. In general, programs don't respond when you click down on the mouse, the action response happens when you let go (the mouse-up event).

Example of nested menus:

Items = "Take | Drop | >Eat | With Fork | With Hands | < | >Emote | Smile | Laugh "

This would display:

Take
Drop
Eat ->
..With Fork
..With Hands
Emote ->
..Smile
..Laugh

(Where Eat and Emote are nested menus)


If the first character of the entire Items string is the "!" character, then the function returns the selected item number rather than the selected string. It still returns an empty string if nothing is selected. The "!" is then removed and the rest of the string treated in the usual way (so you could then start a submenu, for example).

This lets you distinguish between multiple identical items in submenus. 

Only items that generate "active" menu elements are counted. That is, divider lines, grayed-out items, and sub-menus are not counted. The first item is item 1.

For example:

Items = "!Take |-| ^Drop | >Eat | Fork | Hands | < | >Emote | Smile | Laugh "

In this case we would get:

Take: 1
Divider line: (can't be selected)
Drop: (can't be selected)
Eat -> Fork: 2
Eat -> Hands: 3
Emote -> Smile: 4
Emote -> Laugh: 5

Cancelled: empty string

If the first character of the entire Items string is the "~" character, then the menu alignment is specified by the next two characters. The "~xx" characters are then removed and the rest of the string treated in the usual way (so you could then start a submenu, for example).

The two characters following the "~" are the horizontal and vertical alignments, as follows:

Horizontal: L, C or R (left, centre, right)
Vertical: T, C or B (top, centre, bottom)

Default is top left (so the menu aligns to the specified point and appears on the right and underneath). That is, top left is where the menu starts. The letters are not case-sensitive. Anything other than those letters will be ignored.

For example:

Items = "~RBTake | Drop"   -- align cursor on right and bottom of point.

If you want to use both "!" and "~" then use "!" first as that is checked for and then removed from the string. Then it checks for "~" next. After that the normal menu processing takes place.


Summary of special characters in the first column:

! : return numeric result (only in first position of entire string)
~ : specify menu alignment (only in first position of entire string, or after "!")

- : separator line
^ : grayed-out item
+ : checked (ticked) item
> : start of nested menu (rest of line is nested menu title)
< : end of nested menu (rest of line is ignored)

Nested menus can be further nested.

Nested menus added in version 4.52. Numeric results added in version 4.65.
Checked items added in version 4.71. Menu alignment added in version 5.05.

return_value:
If there was an error condition as described above, the empty string.

If the menu was dismissed, or no item selected, the empty string.

Otherwise, the text of the selected item, with leading and trailing spaces removed.

However if the first character of the Items string is the "!" character then, if the menu was not cancelled, a number is returned, starting at 1, being the item number of the selected item. Only active items (ones which can be selected) are counted.

lua_example:
result = WindowMenu (win, 
  WindowInfo (win, 14),  -- x
  WindowInfo (win, 15),   -- y
  "^Sword of Fire|-|Wield|Drop|Wear")

if result ~= "" then
  Send (result .. " 'Sword of Fire' ")
end -- if


name: SetCommandSelection
prototype: long SetCommandSelection(long First, long Last);
summary: Selects specified columns in the command window
vb_example: SetCommandSelection 2, 4
java_example: world.SetCommandSelection (2, 4);
perl_example: $world->SetCommandSelection (2, 4);
return_value: eOK: Set OK
type_of_object: Method
see_also: Send Note PasteCommand SetCommand
python_example: world.SetCommandSelection (2, 4)
doc_name: send
lua_example: SetCommandSelection (2, 4)
description:
Lets you select text in the command window. This is intended for specialized applications like a spell checker where, after finding a spelling mistake, you select the misspelt word.

First - the first character to select (1-relative), so the first character is 1.

If "First" is zero, then any selection is removed.


Last - the last character to select (1-relative).

If "Last" is -1 then the rest of the line is selected. 

Thus, to select everything, make First = 1 and Last = -1.

To put the cursor between characters, specify them backwards. See the example below.


Examples:

SetCommandSelection (2, 4) --> select characters 2 to 4
SetCommandSelection (0, 0) --> select nothing
SetCommandSelection (1, -1) --> select everything
SetCommandSelection (10, -1) --> select column 10 onwards
SetCommandSelection (6, 5) --> put the cursor between column 5 and column 6


If you want to *get* the current selection in the command window, use GetInfo(236) (first character) and GetInfo(237) (last character).


name: WindowDragHandler
summary: Adds a drag handler to a miniwindow hotspot
type_of_object: Method
doc_name: miniwindows
prototype:
long WindowDragHandler(BSTR WindowName, BSTR HotspotId, BSTR MoveCallback, BSTR ReleaseCallback, long Flags);

description:
Adds drag handler callbacks to the nominated hotspot.

If:


* The user clicks in the hotspot; and
* Moves the mouse; and
* There is a MoveCallback function defined (by using this function)

... then the callback function is called every time the mouse moves (regardless of whether it is still over the current miniwindow).

Also, when the mouse is eventually released, the ReleaseCallback function is called. Unlike the existing mousedown and mouseup functions, these two functions are called no matter where the mouse is - it doesn't even have to be over the MUSHclient window.

This lets you do things like move a window around (eg. drag its title bar), or drag something from one window to another.

There are now WindowInfo selectors (17 and 18) which return the current position of the mouse in "client" coordinates. That is, relative to the output window, not relative to the miniwindow. The mouse position in client coordinates could be used to work out where in the output window the mouse is.  

For each miniwindow, WindowInfo selectors 10 to 13 give the current position of that miniwindow (as last drawn), and thus you can work out whether the cursor is over a particular one.

NOTE: Hotspot functions must be visible to MUSHclient when querying the script engine. Thus functions declared as "local" in Lua (or something similar in other languages) will not work.

If you want to change the shape of the cursor as the mouse is being dragged, see SetCursor.

For more information, see:

http://www.gammon.com.au/forum/?id=9254

WindowName - the name of an existing miniwindow.

HotspotId - the hotspot id of an existing hotspot.

MoveCallback - the name of the script function to be called when you move the mouse 

ReleaseCallback - the name of the script function to be called when you release the mouse

Flags - flags to modify dragging behaviour. Leave as zero, these are not currently used.



To cancel a drag handler, just set the function names to empty strings, eg.

WindowDragHandler(win, "hs1", "", "", 0)


The callback functions should look like this:

function drag_move (flags, hotspot_id)

  -- find where it is now
  local posx = WindowInfo (win, 17)  -- where mouse is relative to output window (X)
  local posy = WindowInfo (win, 18)  -- where mouse is relative to output window (Y)
 
  -- reposition window here

  return 0  -- needed for some languages
end -- drag_move


The function return code is ignored, however for some languages, like PHP, you should return 0, otherwise you will get a runtime error.

The flags parameter is a bit mask as follows:

0x01 - Shift key down
0x02 - Control key down
0x04 - Alt key down
0x10 - LH mouse  (from mouse-down)
0x20 - RH mouse  (from mouse-down)
0x40 - double-click  (from mouse-down)


Note that the mouse was not necessarily clicked on the top-left corner of the miniwindow. Thus a mousedown handler should remember the offset from the edge of the miniwindow when the mouse is clicked (WindowInfo selectors 14 and 15). Then to reposition the window (if that is what you are trying to do) you need to subtract that offset from the values returned by WindowInfo selectors 17 and 18, to get the new location for the top-left corner.

See the example below in the Lua section for more details.



WARNING: The callbacks are not functions, but names of functions. That is, they should be supplied as string arguments. The supplied names are looked up in the script space at the appropriate time.

return_value:
eNoSuchWindow - no such miniwindow
eHotspotNotInstalled - no such hotspot
eInvalidObjectLabel - one of the script functions is not a valid function name
eHotspotPluginChanged - the plugin is not the same one as used before for hotspots
eOK - completed OK

see_also:
WindowDeleteAllHotspots WindowDeleteHotspot WindowHotspotInfo WindowHotspotList WindowCreate WindowAddHotspot SetCursor WindowScrollwheelHandler

lua_example:
-- mouse down function - remember how far in from edge of window mouse was

function mousedown(flags, hotspot_id)
  startx, starty = WindowInfo (win, 14), WindowInfo (win, 15)
end -- mousedown

-- mouse release function - do something useful at the destination location

function dragrelease(flags, hotspot_id)
  print ("mouse drag release for " .. hotspot_id)
  print ("released at position", WindowInfo (win, 17), WindowInfo (win, 18))
end -- dragrelease

function dragmove(flags, hotspot_id)
  print ("moved to position", WindowInfo (win, 17), WindowInfo (win, 18))
  
  local posx, posy = WindowInfo (win, 17),
                     WindowInfo (win, 18)
                                                      
  -- move the window to the new location
  WindowPosition(win, posx - startx, posy - starty, 0, 2);
  
  -- change the mouse cursor shape appropriately
  if posx < 0 or posx > GetInfo (281) or
     posy < 0 or posy > GetInfo (280) then
    check (SetCursor ( 11))   -- X cursor
  else
    check (SetCursor ( 1))   -- hand cursor
  end -- if
  
end -- dragmove

-- set up the drag handler
WindowDragHandler (win, "hs1", "dragmove", "dragrelease", 0)

lua_notes:
The two handler function names can be omitted and default to the empty string (ie. no function).

Flags can be omitted and default to zero.


You can use the following constants for the flags parameter (first parameter) to the callback function called when the mouse is moved or released.

miniwin.drag_got_shift = 1
miniwin.drag_got_control = 2
miniwin.drag_got_alt = 4
miniwin.hotspot_got_lh_mouse = 16
miniwin.hotspot_got_rh_mouse = 32
miniwin.hotspot_got_dbl_click = 64


name: SetCursor
prototype: long SetCursor(long Cursor);
summary: Changes the shape of the mouse cursor
return_value: eBadParameter - cursor value is not in the list above eOK - completed OK
type_of_object: Method
see_also: DragHandler
doc_name: miniwindows
lua_example: SetCursor (11) -- make an X cursor
description:
This function lets you change the shape of the cursor during a hotspot drag operation.

The argument a number which indicates what shape the mouse pointer is to take, as follows:

-1: no cursor

0: arrow
1: hand
2: I-beam
3: + symbol
4: wait (hour-glass)
5: up arrow
6: arrow nw-se
7: arrow ne-sw
8: arrow e-w
9: arrow n-s
10: arrow - all ways
11: (X) cannot do action
12: help (? symbol)


This operation is only effective when the mouse is "captured" - basically after a mouse-down but before the corresponding mouse-up. Otherwise the cursor is likely to be promptly restored by MUSHclient's cursor management code, for example to an I-beam cursor if it moves over text, or to the designated cursor if it moves over miniwindow hotspots.

Cursor shape -1 (no cursor) added in version 4.45.

lua_notes:
You can use the following constants for the cursor:

miniwin.cursor_none = -1
miniwin.cursor_arrow = 0
miniwin.cursor_hand = 1
miniwin.cursor_ibeam = 2
miniwin.cursor_plus = 3
miniwin.cursor_wait = 4
miniwin.cursor_up = 5
miniwin.cursor_nw_se_arrow = 6
miniwin.cursor_ne_sw_arrow = 7
miniwin.cursor_ew_arrow = 8
miniwin.cursor_ns_arrow = 9
miniwin.cursor_both_arrow = 10
miniwin.cursor_x = 11
miniwin.cursor_help = 12


name: DatabaseOpen
prototype: long DatabaseOpen(BSTR DbName, BSTR Filename, long Flags);
summary: Opens an SQLite database
type_of_object: Method
see_also: DatabaseClose DatabaseExec DatabaseFinalize DatabasePrepare DatabaseOpen
doc_name: database
description:
Opens or creates a database. Databases can be held in memory or on disk. You need read or write permissions to access the database, as it is stored on disk as a normal disk file.

DbName - a unique ID you choose to identify this database for all other operations on it (Eg. "db").

Filename - the file name on disk. The special filename ":memory:" opens an in-memory database. This can be used to manipulate data (or play with SQL) without actually writing to disk.

Flags -

Open_ReadOnly       = 0x00000001
Open_ReadWrite      = 0x00000002
Open_Create         = 0x00000004
Open_DeleteOnClose  = 0x00000008
Open_Exclusive      = 0x00000010
Open_Main_db        = 0x00000100
Open_Temp_db        = 0x00000200
Open_Transient_db   = 0x00000400
Open_Main_Journal   = 0x00000800
Open_Temp_Journal   = 0x00001000
Open_SubJournal     = 0x00002000
Open_Master_Journal = 0x00004000
Open_NoMutex        = 0x00008000
Open_FullMutex      = 0x00010000

Warning - the SQLite documentation suggests that you choose one of:

Open_ReadOnly (1)
Open_ReadWrite (2) or
Open_ReadWrite + Open_Create (6)

If not, the behaviour of the open may be undefined.

Use DatabaseClose to close the database when you are finished with it.

If the database is still open when the world file is closed, the database is automatically closed.

It is not an error to re-open the same database ID of an existing, open, database, provided the disk file name is the same. This will be treated as a no-operation, so that triggers and aliases can open the database without having to check first if it was already open.

return_value:
0 : success

-6 : Database already exists under a different disk name

Otherwise, an SQLite error code, and the database ID cannot be used

lua_example:
DatabaseOpen ("db",   -- database ID
              GetInfo (66) .. "mytestdb.sqlite",   -- file name
              6)      -- flags

-- do stuff with the database here

DatabaseClose ("db")  -- close it

lua_notes:
The Flags parameter can be omitted, and defaults to 6 (Open_ReadWrite + Open_Create).

The return codes are available in the sqlite3 table in Lua, as follows:

sqlite3.OK = 0
sqlite3.INTEGER = 1
sqlite3.INTERNAL = 2
sqlite3.PERM = 3
sqlite3.ABORT = 4
sqlite3.BUSY = 5
sqlite3.LOCKED = 6
sqlite3.NOMEM = 7
sqlite3.READONLY = 8
sqlite3.INTERRUPT = 9
sqlite3.IOERR = 10
sqlite3.CORRUPT = 11
sqlite3.NOTFOUND = 12
sqlite3.FULL = 13
sqlite3.CANTOPEN = 14
sqlite3.PROTOCOL = 15
sqlite3.EMPTY = 16
sqlite3.SCHEMA = 17
sqlite3.TOOBIG = 18
sqlite3.CONSTRAINT = 19
sqlite3.MISMATCH = 20
sqlite3.MISUSE = 21
sqlite3.NOLFS = 22
sqlite3.FORMAT = 24
sqlite3.RANGE = 25
sqlite3.NOTADB = 26
sqlite3.ROW = 100
sqlite3.DONE = 101


name: DatabaseClose
prototype: long DatabaseClose(BSTR DbName);
summary: Closes an SQLite database
return_value: 0: Closed OK -1 : Database id not found -2 : Database not open
type_of_object: Method
see_also: DatabaseOpen DatabaseExec DatabaseFinalize DatabasePrepare
doc_name: database
lua_example: DatabaseClose ("db") -- close it
description:
Closes an existing SQLite database.

DbName - the unique database ID you assigned when opening the database.


name: DatabaseExec
prototype: long DatabaseExec(BSTR DbName, BSTR Sql);
summary: Executes SQL code against an SQLite database
type_of_object: Method
doc_name: database
description:
This executes SQL on a database previously opened with DatabaseOpen. 

You need to supply the database id of an existing opened database, and the SQL statements to be executed. More than one statement may be supplied, separated by semicolons. If one statement causes an error, execution will be terminated. The most recent error message string (if any) can be obtained by calling DatabaseError.

After successful execution, DatabaseExec will return 0. For more explanation if zero is not returned, call DatabaseError.

You cannot call DatabaseExec if you have called DatabasePrepare but not DatabaseFinalize, as a statement is currently being processed.

DatabaseExec is not suitable for executing SQL code that queries the database for data (like a SELECT statement), as there is no provision for getting the results back. In that situation use DatabasePrepare / DatabaseStep / DatabaseFinalize.

To obtain a single row and value, call DatabaseGetField.

return_value:
0: Executed OK
-1 : Database id not found
-2 : Database not open
-3 : Already have prepared statement

see_also:
DatabaseClose DatabaseExec DatabaseFinalize DatabasePrepare DatabaseOpen DatabaseError DatabaseGetField

lua_example:
DatabaseOpen ("db", GetInfo (66) .. "mytestdb.sqlite", 6)

DatabaseExec ("db", [[
DROP TABLE IF EXISTS weapons;
CREATE TABLE weapons(
        weapon_id INTEGER NOT NULL PRIMARY KEY autoincrement,
        name  TEXT NOT NULL,
        damage INT default 10,
        weight REAL
      );
      ]])
      
DatabaseClose ("db")  -- close it

lua_notes:
The return codes are available in the sqlite3 table in Lua, as follows:

sqlite3.OK = 0
sqlite3.INTEGER = 1
sqlite3.INTERNAL = 2
sqlite3.PERM = 3
sqlite3.ABORT = 4
sqlite3.BUSY = 5
sqlite3.LOCKED = 6
sqlite3.NOMEM = 7
sqlite3.READONLY = 8
sqlite3.INTERRUPT = 9
sqlite3.IOERR = 10
sqlite3.CORRUPT = 11
sqlite3.NOTFOUND = 12
sqlite3.FULL = 13
sqlite3.CANTOPEN = 14
sqlite3.PROTOCOL = 15
sqlite3.EMPTY = 16
sqlite3.SCHEMA = 17
sqlite3.TOOBIG = 18
sqlite3.CONSTRAINT = 19
sqlite3.MISMATCH = 20
sqlite3.MISUSE = 21
sqlite3.NOLFS = 22
sqlite3.FORMAT = 24
sqlite3.RANGE = 25
sqlite3.NOTADB = 26
sqlite3.ROW = 100
sqlite3.DONE = 101


-- ---------------------------------
-- Suggested helper functions for handling errors, and fixing up SQL with quotes inside it are:
-- ---------------------------------

local MUSHclient_Database_Errors = {
  [-1] = "Database id not found",
  [-2] = "Database not open",
  [-3] = "Already have prepared statement",
  [-4] = "Do not have prepared statement",
  [-5] = "Do not have a valid row",
  [-6] = "Database already exists under a different disk name",
  [-7] = "Column number out of range",
  } -- end of MUSHclient_Database_Errors

-- check for errors on a DatabaseXXXXX call
function dbcheck (code)

 if code == sqlite3.OK or       -- no error
    code == sqlite3.ROW or      -- completed OK with another row of data
    code == sqlite3.DONE then   -- completed OK, no more rows
    return code
  end -- if code OK

  -- DatabaseError won't return the negative errors  
  local err = MUSHclient_Database_Errors [code] or DatabaseError(db)
  DatabaseExec (db, "ROLLBACK")  -- rollback any transaction to unlock the database
  error (err, 2)                 -- show error in caller's context

end -- dbcheck 

-- Quote the argument, replacing single quotes with two lots of single quotes.
-- If nil supplied, return NULL (not quoted).
function fixsql (s)
  if s then
    return "'" .. (string.gsub (s, "'", "''")) .. "'"
  else
    return "NULL"
  end -- if
end -- fixsql


name: DatabasePrepare
prototype: long DatabasePrepare(BSTR DbName, BSTR Sql);
summary: Prepares an SQL statement for execution
type_of_object: Method
see_also: DatabaseClose DatabaseExec DatabaseFinalize DatabaseExec DatabaseOpen DatabaseError
doc_name: database
description:
Prepares (compiles) an SQL statement, ready to be executed with DatabaseStep.

You need to supply the database id of an existing opened database, and the SQL statement to be executed. Only one statement should be supplied. If multiple statements are supplied, only the first will be used. (eg. "drop table a; drop table b" - in this case only the first "drop table" would be executed).

If there is a syntax error in your SQL, that will be reported by a non-zero return code from DatabasePrepare. The most recent error message string (if any) can be obtained by calling DatabaseError.

Note that to include single quotes inside a string literal, in your SQL statement they must be doubled. For example:

INSERT INTO weapons (name, damage) VALUES ('Nick''s sword', 42)

Only one statement can be active at once, so after doing a DatabasePrepare you must do DatabaseFinalize before doing another DatabasePrepare. The exception is that if DatabasePrepare returns an error, then you do not need to do DatabaseFinalize because there is no active statement. 

After successfully doing DatabasePrepare, you then need to call DatabaseStep for each row in the query. This is the execution phase. For SQL statements that return multiple rows of data, you need to do DatabaseStep once for each row. For SQL statements that just do one thing (like INSERT INTO) then you only need to call DatabaseStep once.

Also see DatabaseExec if you only need to execute SQL statements (like INSERT INTO) which do not return any results.

return_value:
0: Completed OK
-1 : Database id not found
-2 : Database not open
-3 : Already have prepared statement

Otherwise an SQLite return code. For example:

1: SQL error or missing database
5 : The database file is locked

lua_example:
-- insert a record
DatabasePrepare ("db", "INSERT INTO weapons (name, damage) VALUES ('sword', 42)")  --> returns 0 (sqlite3.OK)
DatabaseStep ("db")   -- returns 101 (sqlite3.DONE)
DatabaseFinalize ("db")  -- returns 0 (sqlite3.OK)


-- see the DatabaseStep entry for a more elaborate example.


-- A suitable function for fixing up strings is this:

-- Quote the argument, replacing single quotes with two lots of single quotes.
-- If nil supplied, return NULL (not quoted).
function fixsql (s)
  if s then
    return "'" .. (string.gsub (s, "'", "''")) .. "'"
  else
    return "NULL"
  end -- if
end -- fixsql

lua_notes:
The return codes are available in the sqlite3 table in Lua, as follows:

sqlite3.OK = 0
sqlite3.INTEGER = 1
sqlite3.INTERNAL = 2
sqlite3.PERM = 3
sqlite3.ABORT = 4
sqlite3.BUSY = 5
sqlite3.LOCKED = 6
sqlite3.NOMEM = 7
sqlite3.READONLY = 8
sqlite3.INTERRUPT = 9
sqlite3.IOERR = 10
sqlite3.CORRUPT = 11
sqlite3.NOTFOUND = 12
sqlite3.FULL = 13
sqlite3.CANTOPEN = 14
sqlite3.PROTOCOL = 15
sqlite3.EMPTY = 16
sqlite3.SCHEMA = 17
sqlite3.TOOBIG = 18
sqlite3.CONSTRAINT = 19
sqlite3.MISMATCH = 20
sqlite3.MISUSE = 21
sqlite3.NOLFS = 22
sqlite3.FORMAT = 24
sqlite3.RANGE = 25
sqlite3.NOTADB = 26
sqlite3.ROW = 100
sqlite3.DONE = 101


name: DatabaseStep
prototype: long DatabaseStep(BSTR DbName);
summary: Executes a previously-prepared SQL statement
type_of_object: Method
doc_name: database
description:
Executes an SQL statement over one row over the database. In the case of a SELECT statement, one row is returned for each call to DatabaseStep.

After successfully doing DatabasePrepare, you then need to call DatabaseStep for each row in the query. This is the execution phase. For SQL statements that return multiple rows of data, you need to do DatabaseStep once for each row. For SQL statements that just do one thing (like INSERT INTO) then you only need to call DatabaseStep once.

DatabaseStep will return SQLITE_ROW (100) if it has returned a row of data, otherwise it will return SQLITE_DONE (101) if it has reached the end of the query. You could make a loop that continues to call DatabaseStep until it no longer returns 100, in order to process every row in the query.

If you want to reprocess the SQL query from the start for some reason, you can call DatabaseReset and the query restarts at the beginning (you would then need to call DatabaseStep again to re-obtain the first row).

return_value:
100: Another row is ready.
101: Completed OK, no further rows.

-1 : Database id not found
-2 : Database not open
-4 : Do not have prepared statement


Otherwise an SQLite return code. For example:

1: SQL error or missing database
5 : The database file is locked
21 : Library used incorrectly

see_also:
DatabaseReset DatabasePrepare DatabaseFinalize DatabaseExec DatabaseOpen DatabaseError DatabaseColumnName DatabaseColumnNames DatabaseColumns DatabaseColumnText DatabaseColumnType DatabaseColumnValue DatabaseColumnValues DatabaseLastInsertRowid

lua_example:
require "tprint"

DatabaseOpen ("db", GetInfo (66) .. "mytestdb.sqlite", 6)

rc = DatabaseExec ("db", [[
DROP TABLE IF EXISTS weapons;
CREATE TABLE weapons(
        weapon_id INTEGER NOT NULL PRIMARY KEY autoincrement,
        name  TEXT NOT NULL,
        damage INT default 10,
        weight REAL
      );
      ]])
      

-- put some data into the database
DatabaseExec ("db", 
  [[
  INSERT INTO weapons (name, damage) VALUES ('sword', 42);
  INSERT INTO weapons (name, damage) VALUES ('mace', 55);
  INSERT INTO weapons (name, damage) VALUES ('staff', 35);
  ]])

-- prepare a query
DatabasePrepare ("db", "SELECT * from weapons ORDER BY name")

-- find the column names
names = DatabaseColumnNames ("db")
tprint (names)

-- execute to get the first row
rc = DatabaseStep ("db")  -- read first row

-- now loop, displaying each row, and getting the next one
while rc == sqlite3.ROW do
  
  print ("")
  values = DatabaseColumnValues ("db")
  tprint (values)

  rc = DatabaseStep ("db")  -- read next row

end -- while loop

-- finished with the statement
DatabaseFinalize ("db")

DatabaseClose ("db")  -- close it

lua_notes:
The return codes are available in the sqlite3 table in Lua, as follows:

sqlite3.OK = 0
sqlite3.INTEGER = 1
sqlite3.INTERNAL = 2
sqlite3.PERM = 3
sqlite3.ABORT = 4
sqlite3.BUSY = 5
sqlite3.LOCKED = 6
sqlite3.NOMEM = 7
sqlite3.READONLY = 8
sqlite3.INTERRUPT = 9
sqlite3.IOERR = 10
sqlite3.CORRUPT = 11
sqlite3.NOTFOUND = 12
sqlite3.FULL = 13
sqlite3.CANTOPEN = 14
sqlite3.PROTOCOL = 15
sqlite3.EMPTY = 16
sqlite3.SCHEMA = 17
sqlite3.TOOBIG = 18
sqlite3.CONSTRAINT = 19
sqlite3.MISMATCH = 20
sqlite3.MISUSE = 21
sqlite3.NOLFS = 22
sqlite3.FORMAT = 24
sqlite3.RANGE = 25
sqlite3.NOTADB = 26
sqlite3.ROW = 100
sqlite3.DONE = 101


name: DatabaseFinalize
prototype: long DatabaseFinalize(BSTR DbName);
summary: Finalizes (wraps up) a previously-prepared SQL statement
type_of_object: Method
doc_name: database
description:
This must be called after calling DatabasePrepare, once you have finished with the current SQL statement. You will not be able to call DatabasePrepare again, until the first one is finalized.

return_value:
0: Completed OK

-1 : Database id not found
-2 : Database not open
-4 : Do not have prepared statement


Otherwise an SQLite return code. For example:

1: SQL error or missing database
5 : The database file is locked
21 : Library used incorrectly

see_also:
DatabaseReset DatabasePrepare DatabaseStep DatabaseExec DatabaseOpen DatabaseError DatabaseColumnName DatabaseColumnNames DatabaseColumns DatabaseColumnText DatabaseColumnType DatabaseColumnValue DatabaseColumnValues DatabaseLastInsertRowid

lua_example:
-- insert a record
DatabasePrepare ("db", "INSERT INTO weapons (name, damage) VALUES ('sword', 42)")  --> returns 0 (sqlite3.OK)
DatabaseStep ("db")   -- returns 101 (sqlite3.DONE)
DatabaseFinalize ("db")  -- returns 0 (sqlite3.OK)

lua_notes:
The return codes are available in the sqlite3 table in Lua, as follows:

sqlite3.OK = 0
sqlite3.INTEGER = 1
sqlite3.INTERNAL = 2
sqlite3.PERM = 3
sqlite3.ABORT = 4
sqlite3.BUSY = 5
sqlite3.LOCKED = 6
sqlite3.NOMEM = 7
sqlite3.READONLY = 8
sqlite3.INTERRUPT = 9
sqlite3.IOERR = 10
sqlite3.CORRUPT = 11
sqlite3.NOTFOUND = 12
sqlite3.FULL = 13
sqlite3.CANTOPEN = 14
sqlite3.PROTOCOL = 15
sqlite3.EMPTY = 16
sqlite3.SCHEMA = 17
sqlite3.TOOBIG = 18
sqlite3.CONSTRAINT = 19
sqlite3.MISMATCH = 20
sqlite3.MISUSE = 21
sqlite3.NOLFS = 22
sqlite3.FORMAT = 24
sqlite3.RANGE = 25
sqlite3.NOTADB = 26
sqlite3.ROW = 100
sqlite3.DONE = 101


name: DatabaseColumnType
prototype: long DatabaseColumnType(BSTR DbName, long Column);
summary: Returns the type of data in an SQL column
type_of_object: Method
doc_name: database
lua_example: t = DatabaseColumnType ("db", 2) --> 3 (if the column is text)
description:
You can use this, after successfully doing a DatabaseStep, to find the type of data actually in each column of the current row.

Data types are:

Integer: 1 
Float: 2 
Text: 3 
Blob: 4 
Null: 5 

This can be called after DatabaseStep to find whether a particular column is text, a number, or NULL (no data).

Columns start at 1 for the first column, up to the number returned by DatabaseColumns.

return_value:
A positive integer  representing the data type of the specified column, as follows:

Integer: 1 
Float: 2 
Text: 3 
Blob: 4 
Null: 5 

Otherwise, an error code:

-1 : Database id not found
-2 : Database not open
-4 : Do not have prepared statement
-5 : Do not have a valid row
-7 : Column number out of range

see_also:
DatabaseReset DatabasePrepare DatabaseFinalize DatabaseExec DatabaseOpen DatabaseError DatabaseColumnName DatabaseColumnNames DatabaseColumns DatabaseColumnText DatabaseColumnType DatabaseColumnValue DatabaseColumnValues DatabaseLastInsertRowid


name: DatabaseColumns
prototype: long DatabaseColumns(BSTR DbName);
summary: Find how many columns will be returned by an SQL statement
type_of_object: Method
doc_name: database
lua_example: columns = DatabaseColumns ("db")
description:
You can use this, after successfully doing a DatabasePrepare, to find the number of columns that each row will return. This number might be zero for SQL statements that do not return any data.

You can do this before doing a DatabaseStep, because the column names (and number of columns) is a property of the SQL statement, whether or not any rows are found that actually match the query.

return_value:
A positive integer, or zero,  representing the number of columns that the prepared SQL statement will return.


Otherwise, an error code:

-1 : Database id not found
-2 : Database not open
-4 : Do not have prepared statement

see_also:
DatabaseReset DatabasePrepare DatabaseFinalize DatabaseExec DatabaseOpen DatabaseError DatabaseColumnName DatabaseColumnNames DatabaseColumnText DatabaseColumnType DatabaseColumnValue DatabaseColumnValues DatabaseLastInsertRowid


name: DatabaseColumnName
prototype: BSTR DatabaseColumnName(BSTR DbName, long Column);
summary: Find the name of a specified column returned by an SQL statement
type_of_object: Method
doc_name: database
lua_example: name = DatabaseColumnName ("db", 5) --> the name of column 5
description:
You can use this, after successfully doing a DatabasePrepare, to find the names of columns that each row will return. 

You can do this before doing a DatabaseStep, because the column names (and number of columns) is a property of the SQL statement, whether or not any rows are found that actually match the query.

The column name is the name given in the "AS" clause in the query, if any. Otherwise SQLite assigns a column name, which is not guaranteed to be consistent between versions. Often the column name will simply be the name of the variable being queried, however calculations may return generated names.

For example, using this SQL statement:

DatabasePrepare ("db", "SELECT name AS 'weapon name', damage * 5 from weapons")


The returned column names were 'weapon name' and 'damage * 5'.

Columns start at 1 for the first column, up to the number returned by DatabaseColumns.

Also see DatabaseColumnNames which returns a table of all the column names.

return_value:
The name of the column.

If a parameter is invalid (eg. database not open, bad column number) an empty string is returned.

see_also:
DatabaseReset DatabasePrepare DatabaseFinalize DatabaseExec DatabaseOpen DatabaseError DatabaseColumns DatabaseColumnNames DatabaseColumnText DatabaseColumnType DatabaseColumnValue DatabaseColumnValues DatabaseLastInsertRowid


name: DatabaseColumnNames
prototype: VARIANT DatabaseColumnNames(BSTR DbName);
summary: Return a table of all the columns returned by an SQL statement
return_value: A table of all the column names, indexed by column number (ie. 1 is the first column).
type_of_object: Method
doc_name: database
lua_notes: Lua returns nil if there are no columns.
description:
You can use this, after successfully doing a DatabasePrepare, to find the names of columns that each row will return. 

You can do this before doing a DatabaseStep, because the column names (and number of columns) is a property of the SQL statement, whether or not any rows are found that actually match the query.

The column name is the name given in the "AS" clause in the query, if any. Otherwise SQLite assigns a column name, which is not guaranteed to be consistent between versions. Often the column name will simply be the name of the variable being queried, however calculations may return generated names.

For example, using this SQL statement:

DatabasePrepare ("db", "SELECT name AS 'weapon name', damage * 5 from weapons")


The returned column names were 'weapon name' and 'damage * 5'.

Columns start at 1 for the first column, up to the number returned by DatabaseColumns.

Also see DatabaseColumnName which returns an entry for a single column.

see_also:
DatabaseReset DatabasePrepare DatabaseFinalize DatabaseExec DatabaseOpen DatabaseError DatabaseColumns DatabaseColumnName DatabaseColumnText DatabaseColumnType DatabaseColumnValue DatabaseColumnValues DatabaseLastInsertRowid

lua_example:
DatabasePrepare ("db", "SELECT * from weapons")
t = DatabaseColumnNames ("db")  --> the names of all columns


name: DatabaseColumnText
prototype: BSTR DatabaseColumnText(BSTR DbName, long Column);
summary: Returns the contents of an SQL column, as text
return_value: The contents of the column, as a string.
type_of_object: Method
doc_name: database
lua_example: x = DatabaseColumnText ("db", 2) --> the contents of column 2, converted to a text string
description:
You can use this, after successfully doing a DatabaseStep, to get the data in a particular column, converted to text.

Columns start at 1 for the first column, up to the number returned by DatabaseColumns.

see_also:
DatabaseReset DatabasePrepare DatabaseFinalize DatabaseExec DatabaseOpen DatabaseError DatabaseColumnName DatabaseColumnNames DatabaseColumns DatabaseColumnType DatabaseColumnType DatabaseColumnValue DatabaseColumnValues DatabaseLastInsertRowid


name: DatabaseColumnValue
prototype: VARIANT DatabaseColumnValue(BSTR DbName, long Column);
summary: Returns the contents of an SQL column, as text, float, integer, or null
type_of_object: Method
doc_name: database
lua_example: x = DatabaseColumnValue ("db", 2) --> the contents of column 2
lua_notes: Lua returns nil for a NULL value.
description:
You can use this, after successfully doing a DatabaseStep, to get the data in a particular column, in the appropriate format: text, floating point number, integer or null.

Columns start at 1 for the first column, up to the number returned by DatabaseColumns.

return_value:
The contents of the column, as a string, long, double or empty variant.

Returns the null variant if there is an error, such as invalid database id, no current row, etc.

see_also:
DatabaseReset DatabasePrepare DatabaseFinalize DatabaseExec DatabaseOpen DatabaseError DatabaseColumnName DatabaseColumnNames DatabaseColumns DatabaseColumnType DatabaseColumnType DatabaseColumnText DatabaseColumnValues DatabaseLastInsertRowid


name: DatabaseColumnValues
prototype: VARIANT DatabaseColumnValues(BSTR DbName);
summary: Returns the contents of all the SQL columns after a step
type_of_object: Method
doc_name: database
lua_example: t = DatabaseColumnValues ("db") --> the contents of all columns
lua_notes: Lua returns nil for a NULL value.
description:
You can use this, after successfully doing a DatabaseStep, to get the data in all particular columns, as a table, in the appropriate format: text, floating point number, integer or null.

The table is indexed to start at 1 for the first column, up to the number returned by DatabaseColumns.

return_value:
The contents of all columns, as a table. Each item contains a string, long, double or empty variant.

see_also:
DatabaseReset DatabasePrepare DatabaseFinalize DatabaseExec DatabaseOpen DatabaseError DatabaseColumnName DatabaseColumnNames DatabaseColumns DatabaseColumnType DatabaseColumnType DatabaseColumnText DatabaseColumnValue DatabaseLastInsertRowid


name: DatabaseReset
prototype: long DatabaseReset(BSTR DbName);
summary: Resets a previously-prepared SQL statement to the start
description: Resets a previously-prepared SQL statement to start iterating again from the beginning.
type_of_object: Method
doc_name: database
lua_example: DatabaseReset ("db") -- back to the start
return_value:
0: Completed OK

-1 : Database id not found
-2 : Database not open
-4 : Do not have prepared statement


Otherwise an SQLite return code. For example:

1: SQL error or missing database
5 : The database file is locked
21 : Library used incorrectly

see_also:
DatabaseStep DatabasePrepare DatabaseFinalize DatabaseExec DatabaseOpen DatabaseError DatabaseColumnName DatabaseColumnNames DatabaseColumns DatabaseColumnText DatabaseColumnType DatabaseColumnValue DatabaseColumnValues DatabaseLastInsertRowid


name: DatabaseError
prototype: BSTR DatabaseError(BSTR DbName);
summary: Returns an English string describing the most recent SQL error
return_value: The error message.
type_of_object: Method
doc_name: database
description:
Call this after one of the other Database routines returns an error code (generally, a code other than 0, 100 or 101).

This will return an explanatory string.

To help with debugging however, codes 100 and 101 also return:

100: "row ready"
101: "finished"

Warning: Since you do not pass the error code into this function, it will not correctly handle the "internal" MUSHclient errors (such as database not open). To handle them correctly you need to test for negative error numbers, as shown in the Lua example below.

see_also:
DatabaseReset DatabasePrepare DatabaseFinalize DatabaseExec DatabaseOpen DatabaseStep DatabaseColumnName DatabaseColumnNames DatabaseColumns DatabaseColumnText DatabaseColumnType DatabaseColumnValue DatabaseColumnValues DatabaseLastInsertRowid

lua_example:
print (DatabaseError ("db"))

--

---
--- Example of handling internal errors, and SQLite3 errors
---

local MUSHclient_Database_Errors = {
  [-1] = "Database id not found",
  [-2] = "Database not open",
  [-3] = "Already have prepared statement",
  [-4] = "Do not have prepared statement",
  [-5] = "Do not have a valid row",
  [-6] = "Database already exists under a different disk name",
  [-7] = "Column number out of range",
  } -- end of MUSHclient_Database_Errors

-- check for errors on a DatabaseXXXXX call
function dbcheck (code)

 if code == sqlite3.OK or       -- no error
    code == sqlite3.ROW or      -- completed OK with another row of data
    code == sqlite3.DONE then   -- completed OK, no more rows
    return code
  end -- if code OK

  -- DatabaseError won't return the negative errors  
  local err = MUSHclient_Database_Errors [code] or DatabaseError(db)
  DatabaseExec (db, "ROLLBACK")  -- rollback any transaction to unlock the database
  error (err, 2)                 -- show error in caller's context

end -- dbcheck


name: DatabaseTotalChanges
prototype: long DatabaseTotalChanges(BSTR DbName);
summary: Returns a count of the total changes to the database
type_of_object: Method
see_also: DatabaseChanges DatabaseLastInsertRowid DatabaseExec DatabaseStep
doc_name: database
lua_example: changes = DatabaseTotalChanges ("db")
description:
This function returns the number of row changes caused by INSERT, UPDATE or DELETE statements since the database connection was opened. The count includes all changes from all trigger contexts. However, the count does not include changes used to implement REPLACE constraints, do rollbacks or ABORT processing, or DROP table processing. The changes are counted as soon as the statement that makes them is completed (when the statement handle is passed to DatabaseReset or DatabaseFinalize).

return_value:
A positive integer, or zero, indicating the count of changes.

Otherwise:

-1 : Database id not found
-2 : Database not open


name: DatabaseChanges
prototype: long DatabaseChanges(BSTR DbName);
summary: Returns a count of the changes to the database by the most recent SQL statement
type_of_object: Method
see_also: DatabaseTotalChanges DatabaseLastInsertRowid DatabaseExec DatabaseStep
doc_name: database
lua_example: changes = DatabaseChanges ("db")
description:
This function returns the number of database rows that were changed or inserted or deleted by the most recently completed SQL statement on the database connection specified by the first parameter. Only changes that are directly specified by the INSERT, UPDATE, or DELETE statement are counted. Auxiliary changes caused by triggers are not counted. Use the DatabaseTotalChanges function to find the total number of changes including changes caused by triggers.

return_value:
A positive integer, or zero, indicating the count of changes.

Otherwise:

-1 : Database id not found
-2 : Database not open


name: DatabaseLastInsertRowid
prototype: BSTR DatabaseLastInsertRowid(BSTR DbName);
summary: Returns the most recently automatically allocated database key
return_value: A string which is the most recently-allocated key. May be zero if there is no such key.
type_of_object: Method
see_also: DatabaseTotalChanges DatabaseChanges DatabaseExec DatabaseStep
doc_name: database
lua_example: last_key = DatabaseLastInsertRowid ("db")
description:
This returns a string which is the most recent automatically allocated database key (for example, if you are using autoincrement on the primary key). Internally it is a 64-bit number, but since there is no ready mechanism for returning 64-bit numbers via the scripting interface, MUSHclient converts it to a string, and returns that.


name: DatabaseList
prototype: VARIANT DatabaseList();
summary: Lists all databases
type_of_object: Method
see_also: DatabaseInfo
doc_name: database
lua_notes: Lua returns nil if there are no databases.
description:
This returns a list of all databases created for this world. You could use this to find which databases have been created, and then use DatabaseInfo to find information about each one.

return_value:
If there are no databases then the return value is empty. Use "IsEmpty" to test for this possibility.

Otherwise, it returns a variant array containing the names of all the databases. Use "ubound" to find the number of databases in the list. You can then use "DatabaseInfo" to find details about each database.

lua_example:
-- show all databases
databases = DatabaseList()

if databases then
  for _, v in ipairs (databases) do 
    Note (v) 
  end
end -- if any


name: DatabaseInfo
prototype: VARIANT DatabaseInfo(BSTR DbName, long InfoType);
summary: Returns information about a database
type_of_object: Method
see_also: DatabaseList
doc_name: database
lua_example: DatabaseInfo ("db", 4) --> get count of columns
lua_notes: Lua returns nil instead of a NULL or EMPTY variant.
description:
This returns information about a particular database. 

DbName - the identifying name of an existing database (as supplied to DatabaseOpen). Not the file name.

InfoType - the information you want:

1 - Name of database on disk

2 - Has a DatabasePrepare been validly done recently (and is still active)?

3 - Has a valid row been returned by DatabaseStep?

4 - Count of columns returned from the last DatabasePrepare.

return_value:
The specified information about the database, as described above.
An EMPTY variant, if the database does not exist.
A NULL variant if the InfoType is not a valid type.


name: FlashIcon
prototype: void FlashIcon();
summary: Flashes the MUSHclient icon on the Windows taskbar
vb_example: FlashIcon
return_value: None.
type_of_object: Method
doc_name: Utils
lua_example: FlashIcon ( )
description:
This function flashes the MUSHclient icon on the Windows taskbar in the same way that MUSHclient does if you have checked the option "New activity flashes taskbar".


name: WindowHotspotTooltip
prototype: long WindowHotspotTooltip(BSTR WindowName, BSTR HotspotId, BSTR TooltipText);
summary: Changes the tooltip text for a hotspot in a miniwindow
return_value: eNoSuchWindow - no such miniwindow eHotspotNotInstalled - no such hotspot eOK - completed OK
type_of_object: Method
doc_name: miniwindows
lua_example: WindowHotspotTooltip (win, "hs1", "Click here to be cured")
description:
This function lets you change the tooltip text for an existing hotspot.

For more information, see:

 http://www.gammon.com.au/mushclient/mw_hotspots.htm

WindowName - the name of an existing miniwindow. Names are case-sensitive.

HotspotId - the hotspot id associated with this particular hotspot. Hotspot IDs are case-sensitive.

TooltipText - the text here is shown automatically if you "hover" the mouse over the hotspot for about a second. It is then removed after a few seconds. This is intended for help messages (maximum 999 characters). If there is a tab character (0x09) in the tooltip text, the text before the tab is considered the tooltip title (shown in bold on a separate line), and the rest of the text is the non-bold tooltip text.

see_also:
WindowDeleteAllHotspots WindowDeleteHotspot WindowHotspotInfo WindowHotspotList WindowCreate WindowDragHandler WindowAddHotspot


name: WindowDrawImageAlpha
summary: Draws an image into a miniwindow respecting the alpha channel
type_of_object: Method
doc_name: miniwindows
lua_example: WindowDrawImageAlpha (win, "im", 20, 20, 0, 0, 1)
prototype:
long WindowDrawImageAlpha(BSTR WindowName, BSTR ImageId, long Left, long Top, long Right, long Bottom, double Opacity, long SrcLeft, long SrcTop);

description:
This copies an image to the miniwindow, using the alpha channel to show transparent areas.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

ImageId - an image id that you have loaded (which must have an alpha channel - generally this means it will be 32 bits per pixel, which is 8 bits for each of red, green and blue, and 8 bits for the alpha information).

Left, Top, Right, Bottom - describes the rectangle to be drawn to.

Opacity - the amount of opacity, between 0 and 1 (floating-point number). An opacity of 0 means you will not see the drawn image. An opacity of 1 means the image is fully drawn (apart from where the alpha channel makes part of it opaque). An opacity of 0.5 means the image is merged 50% with the original contents of the miniwindow.

SrcLeft, SrcTop - the source offset in the original image (use 0,0 to get the whole image). 

The intention of allowing sub-images was so that you could make up a map by having lots of small images (eg. houses, trees, rocks). Now instead of having to load hundreds of tiny image files into memory, which would doubtless take a while to open all those files, you open a single, larger, file in which the various sub-images are "tiled". For example, you might allocate a 32 x 32 pixel square for each image. Now by selecting the appropriate tile you can copy the sub-image from the main image.

For more information, see:

http://www.gammon.com.au/forum/?id=9568

return_value:
eNoSuchWindow - no such miniwindow

eImageNotInstalled - that image was not loaded with WindowLoadImage (or WindowLoadImageMemory), or the image does not have an alpha channel.

eBadParameter - opacity not in range 0 to 1.

eOK - completed OK

see_also:
WindowCreate WindowImageList WindowDrawImage WindowImageInfo WindowImageOp WindowCreateImage WindowDrawImageAlpha


name: WindowGetImageAlpha
summary: Draws the alpha channel of an image into a miniwindow
type_of_object: Method
doc_name: miniwindows
lua_example: WindowGetImageAlpha (win, "im", 20, 20, 0, 0)
prototype:
long WindowGetImageAlpha(BSTR WindowName, BSTR ImageId, long Left, long Top, long Right, long Bottom, long SrcLeft, long SrcTop);

description:
This copies the alpha channel of an image to the miniwindow, showing the alpha information as grayscale.

The alpha channel could be used when copying an image onto the miniwindow using the WindowMergeImageAlpha function.

Thus you could use WindowGetImageAlpha to create a scratch window (one not visible to the player) which holds the alpha information. This could then be turned into another image by using WindowImageFromWindow. This image is now available for use with WindowMergeImageAlpha to selectively copy the image to another miniwindow (this image would be used as the MaskId).

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw. (In the case of WindowGetImageAlpha you would probably never want to actually show the image, as it is just the alpha, or mask, channel).

Parameters:

WindowName - the name of an existing miniwindow.

ImageId - an image id that you have loaded (which must have an alpha channel - generally this means it will be 32 bits per pixel, which is 8 bits for each of red, green and blue, and 8 bits for the alpha information).

Left, Top, Right, Bottom - describes the rectangle to be drawn to.

SrcLeft, SrcTop - the source offset in the original image (use 0,0 to get the whole image).

return_value:
eNoSuchWindow - no such miniwindow

eImageNotInstalled - that image was not loaded with WindowLoadImage (or WindowLoadImageMemory), or the image does not have an alpha channel.

eOK - completed OK

see_also:
WindowCreate WindowImageList WindowDrawImage WindowImageInfo WindowImageOp WindowCreateImage WindowDrawImageAlpha


name: WindowScrollwheelHandler
prototype: long WindowScrollwheelHandler(BSTR WindowName, BSTR HotspotId, BSTR MoveCallback);
summary: Adds a scroll-wheel handler to a miniwindow hotspot
type_of_object: Method
doc_name: miniwindows
lua_notes: The handler function name can be omitted and default to the empty string (ie. no function).
description:
Adds a scroll-wheel handler callback to the nominated hotspot.

If:


* The user moves the scroll wheel over a miniwindow hotspot; and
* There is a MoveCallback function defined (by using this function)

... then the callback function is called.



To cancel a scroll wheel handler, just set the function name to the empty string, eg.

WindowScrollwheelHandler(win, "hs1", "")


The callback function should look like this:

function wheel_move (flags, hotspot_id)

  if bit.band (flags, 0x100) ~= 0 then
    -- wheel scrolled down (towards you)
  else
    -- wheel scrolled up (away from you)
  end -- if

  return 0  -- needed for some languages
end -- wheel_move


The flags parameter is a bit mask as follows:

0x01 - Shift key down
0x02 - Control key down
0x04 - Alt key down
0x100 - Scroll wheel scrolled down (towards you)

In Lua you can use bit.band (as illustrated above) to test individual flags. In other languages you can use bit manipulation tests to check the flags. For example, in VBscript if flags is >= 256 then the mouse wheel was scrolled towards you.


The function return code is ignored, however for some languages, like PHP, you should return 0, otherwise you will get a runtime error.



WARNING: The callbacks is not a function, but the name of a function. That is, it should be supplied as a string argument. The supplied name is looked up in the script space at the appropriate time.

return_value:
eNoSuchWindow - no such miniwindow
eHotspotNotInstalled - no such hotspot
eInvalidObjectLabel - the script function is not a valid function name
eHotspotPluginChanged - the plugin is not the same one as used before for hotspots
eOK - completed OK

see_also:
WindowDeleteAllHotspots WindowDeleteHotspot WindowHotspotInfo WindowHotspotList WindowCreate WindowAddHotspot SetCursor WindowDragHandler

lua_example:
function wheel_move (flags, hotspot_id)

 if bit.band (flags, 0x100) ~= 0 then
    -- wheel scrolled down (towards you)
  else
    -- wheel scrolled up (away from you)
  end -- if

  return 0  -- needed for some languages
end -- wheel_move

WindowScrollwheelHandler(win, "hs1", "wheel_move")


name: WindowResize
prototype: long WindowResize(BSTR WindowName, long Width, long Height, long BackgroundColour);
summary: Resizes a miniwindow
type_of_object: Method
see_also: WindowInfo WindowList WindowShow WindowDelete WindowCreate
doc_name: miniwindows
lua_example: WindowResize ("inventory", 300, 400, ColourNameToRGB ("red")) -- resize window to 300 x 400
description:
This resizes an existing miniwindow of the given name.

If the new size is larger than the existing size the BackgroundColour is used to fill any newly exposed area. 

Any existing contents of the miniwindow are copied to the top-left corner of the new window.

The output window is not automatically redrawn. Call Redraw or WindowShow to cause the new size to become visible.

Any existing hotspots, images, and fonts are preserved. All other window parameters for this miniwindow are unchanged.


PARAMETERS:

WindowName - the name of an existing miniwindow. The name may not be the empty string.

NOTE: Window names are case-sensitive.

Width, Height - the width and height of the window, in pixels. The minimum size is 0, 0.


BackgroundColour - this is the RGB code for the colour is used to replace any pixels which are now visible, which were not previously (if the new size is larger than the old one).

return_value:
eNoNameSpecified - miniwindow name must be specified
eBadParameter - width or height less than zero
eOK - success


name: WindowMoveHotspot
summary: Moves a hotspot in a miniwindow
type_of_object: Method
doc_name: miniwindows
lua_example: WindowMoveHotspot(win, "hs1", 20, 20, 80, 40) -- new rectangle
prototype:
long WindowMoveHotspot(BSTR WindowName, BSTR HotspotId, long Left, long Top, long Right, long Bottom);

description:
Moves a hotspot in a miniwindow. The miniwindow must already exist. The hotspot must already exist.

This lets you reposition a hotspot (for example, if the window is resized).


For more information about hotspots see:

 http://www.gammon.com.au/mushclient/mw_hotspots.htm



WindowName - the name of an existing miniwindow. Names are case-sensitive.

HotspotId - the hotspot id of this particular hotspot. Hotspot IDs are case-sensitive.

Left, Top, Right, Bottom - describes the new hotspot rectangle.

return_value:
eNoSuchWindow - no such miniwindow
eHotspotNotInstalled - this hotspot has not been defined for this window
eOK - completed OK

see_also:
WindowDeleteAllHotspots WindowDeleteHotspot WindowHotspotInfo WindowHotspotList WindowCreate WindowDragHandler WindowHotspotTooltip WindowAddHotspot


name: WindowTransformImage
summary: Draws an image into a miniwindow with optional rotation, scaling, reflection and shearing
type_of_object: Method
doc_name: miniwindows
prototype:
long WindowTransformImage(BSTR WindowName, BSTR ImageId, float Left, float Top, short Mode, float Mxx, float Mxy, float Myx, float Myy);

description:
This copies an image to the miniwindow. You specify effectively a "matrix" which is applied to each pixel position, so that the image can be rotated, scaled, reflected, sheared and translated.

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, Repaint or Redraw.

Parameters:

WindowName - the name of an existing miniwindow.

ImageId - an image id that you have loaded.

Left, Top - the offset in the destination miniwindow for the image

Mode - the method of drawing the image:

1 - Copy non-transparently to the destination position.

2 - Not used.

3 - Do a transparent copy, where the pixel at the left,top corner (pixel position 0,0) is considered the transparent colour. Any pixels that exactly match that colour are not copied. WARNING - do not choose black or white as the transparent colour as that throws out the calculations. Choose some other colour (eg. purple) - you won't see that colour anyway.

The position of each destination pixel (x' and y') is given by:

  x' = (x * Mxx) + (y * Mxy) + Left 
  y' = (x * Myx) + (y * Myy) + Top 


Note that if you draw a monchrome image, such as one set up by WindowCreateImage then the pen colour from the most recent drawing operation is used as the foreground colour, and the brush colour for the background colour. Thus you may want to draw a small rectangle (eg. 1 x 1 pixel) with WindowCircleOp to establish those colours first.

For example images and code, see:

http://www.gammon.com.au/forum/?id=10527


Some examples of rotating, scaling, shearing etc. can be found below in the Lua examples.

Note that in some cases you need to also modify the Left and Top parameters or you may not see the result. For example, reflecting an image is likely to reflect it off the side of the bitmap, so you need to add the size of the image back in, to put it back in its original place. The forum posting mentioned above has a discussion about this, and more detailed examples.

return_value:
eNoSuchWindow - no such miniwindow

eImageNotInstalled - that image was not loaded with WindowLoadImage or WindowLoadImageMemory

eBadParameter - drawing mode not in list above or not available due to being run under Windows 95 or earlier

eOK - completed OK

see_also:
WindowCreate WindowImageList WindowDrawImage WindowImageInfo WindowImageOp WindowCreateImage WindowDrawImageAlpha WindowDrawImage

lua_example:
-- IDENTITY COPY (ie. copy without changing)

WindowTransformImage (win, imageid, 0, 0, miniwin.image_copy, 1, 0, 0, 1) 


-- TRANSLATE

-- move in X direction
WindowTransformImage (win, imageid, 100, 0, miniwin.image_copy, 1, 0, 0, 1) 

-- move in Y direction
WindowTransformImage (win, imageid, 0, 100, miniwin.image_copy, 1, 0, 0, 1) 


-- REFLECT ON THE X AXIS

WindowTransformImage (win, imageid, 0, 0,  miniwin.image_copy,  -1,  0,  0,  1) 


-- REFLECT ON THE Y AXIS

WindowTransformImage (win, imageid, 0, 0,  miniwin.image_copy,  1,  0,  0,  -1) 


-- REFLECT ON BOTH AXES (ROTATE 180 DEGREES)

WindowTransformImage (win, imageid, 0, 0,  miniwin.image_copy,  -1,  0,  0,  -1) 


-- ROTATE

-- rotation angle in degrees
local angle = 30

-- angle converted to radians
local radians = math.rad (angle)

-- calculate sine and cosine
local sine   = math.sin (radians)
local cosine = math.cos (radians)

-- rotate counterclockwise
WindowTransformImage (win, imageid, 0, 0, miniwin.image_copy, cosine, sine,  -sine,  cosine)

-- rotate clockwise
WindowTransformImage (win, imageid, 0, 0, miniwin.image_copy, cosine, -sine,  sine,  cosine) 


-- SHEAR

-- shear vertically right side downwards
WindowTransformImage (win, imageid, 0, 0, miniwin.image_copy,  1,  0,  1,  1) 

-- shear horizontally, bottom to the right
WindowTransformImage (win, imageid, 0, 0,  miniwin.image_copy,  1,  0.5,  0,  1) 


-- SCALE

-- make 1.5 times larger
WindowTransformImage (win, imageid, 0, 0, miniwin.image_copy, 1.5, 0, 0, 1.5) 

-- reduce to 50%
WindowTransformImage (win, imageid, 0, 0, miniwin.image_copy, 0.5, 0, 0, 0.5)

lua_notes:
You can use the following constants for the mode:

miniwin.image_copy = 1
miniwin.image_transparent_copy = 3


name: SetScroll
prototype: long SetScroll(long Position, BOOL Visible);
summary: Sets the scroll bar position, and hides or shows it
return_value: eOK - success
type_of_object: Method
see_also: GetInfo
lua_notes: The Visible flag is optional and defaults to true.
description:
This lets you do two things:

    * Hide the existing scroll bar if desired
    * Set the "scroll position" in the output window

The first feature (hiding the scroll bar) lets you, well, hide it, so that you can draw your own wherever you want (eg. with a themed miniwindow somewhere near where the text appears).

The second feature lets your code scroll the text around (so you can still use the existing output buffer) in response to the player clicking and dragging on "your" thumb, or arrows.

A position of -1 means "the end of the window" (which is the number of lines multiplied by the size of the font, less the size of the output window).

A position of -2 means "no change".

You can use GetInfo (296) to find the current scroll-bar position (and thus add or subtract from it, to scroll up or down small amounts (like a line or a page).

You can use GetInfo (120) to find if the scroll-bar is currently hidden or not.

The existing code adds the font height (GetInfo (212)) to the current scroll position to scroll downwards a line, and subtracts it to scroll up a line.

To scroll up or down pages you need to find the size of the output window text rectangle, and add or subtract that.

lua_example:
SetScroll (0, false)  -- hide scroll bar, go to top of window
SetScroll (-1, false) -- hide scroll bar, go to end of window

SetScroll (-2, false) -- hide scroll bar, do not change position
SetScroll (-2, true)  -- show scroll bar, do not change position


name: Menu
prototype: BSTR Menu(BSTR Items, BSTR Default);
summary: Creates a pop-up menu inside the command window
type_of_object: Method
see_also: WindowMenu
doc_name: utils
lua_notes: The Default parameter is optional and defaults to the empty string (ie. no default).
description:
This creates a pop-up menu inside the command window. This is intended to let you have context-sensitive items (or helpful reminders of MUD comamnds).

Items: A string containing the menu items to be displayed, see below.
Default: If provided, this item is selected.

The Items parameter is a string, containing the menu items to be displayed, separated by the "|" character. Leading and trailing spaces are removed from each item.

For example:  Item = "Take|Wield|Drop|Equip"

There must be at least one item,  or an empty string is returned.

The return value is the selected item, if any. If no item is selected (ie. the menu is dismissed) then an empty string will be returned.

return_value:
If there was an error condition as described above, the empty string.

If the menu was dismissed, or no item selected, the empty string.

Otherwise, the text of the selected item, with leading and trailing spaces removed.

lua_example:
-- make Ctrl+F2 show various options, an paste into command window

AcceleratorTo ( "Ctrl+F2" , 
                'PasteCommand (Menu ("chat|yell|ask|say"))', 
              sendto.script) 


-- display all functions
result = Menu (table.concat (utils.functionlist ( ), "|" ))


name: DatabaseGetField
prototype: VARIANT DatabaseGetField(BSTR Name, BSTR Sql);
summary: Returns a single field from an SQL database
type_of_object: Method
see_also: DatabaseClose DatabaseExec DatabaseFinalize DatabasePrepare DatabaseOpen DatabaseError DatabaseExec
doc_name: database
lua_notes: Returns nil on error.
description:
This executes SQL on a database previously opened with DatabaseOpen. 

It lets you obtain a single value more easily than doing a DatabasePrepare / DatabaseStep / DatabaseColumnValue / DatabaseFinalize in the cases where you just want to establish a single thing (eg. the count of spells in a table).

You need to supply the database id of an existing opened database, and the SQL statement to be executed. 

You cannot call DatabaseGetField if you have called DatabasePrepare but not DatabaseFinalize, as a statement is currently being processed.

The function effectively does this:

DatabasePrepare (Name, Sql)

If unsuccessful, exit with null variant.

Otherwise:
  DatabaseStep (Name)

If successful, and a row was returned, then:
  result = DatabaseColumnValue (Name, 1)

DatabaseFinalize (Name)


If successful, then the value for the first column of the first row is the return value, otherwise the null variant (nil in Lua).

return_value:
The contents of the column, as a string, long, double or empty variant.

Returns the null variant if there is an error, such as invalid database id, no current row, etc.

lua_example:
DatabaseOpen ("db", GetInfo (82), 1)

value = DatabaseGetField ("db", 
                          "SELECT value FROM control WHERE name = 'Version' ")

DatabaseClose ("db")


name: WindowSetZOrder
prototype: long WindowSetZOrder(BSTR WindowName, long Order);
summary: Sets the Z-Order for a miniwindow
return_value: eNoSuchWindow - no such miniwindow eOK - success
type_of_object: Method
doc_name: miniwindows
lua_example: WindowSetZOrder (win, 20)
description:
Sets a Z-Order (drawing order) for the miniwindow. 

Note that changes to miniwindows will not become visible until the output window is redrawn. This happens when new (visible) lines arrive from the MUD, or if you call WindowShow, or Redraw.

Parameters:

WindowName - the name of an existing miniwindow. 

Order - the order to draw the window. Lower is drawn sooner. Windows with the same Z-Order are drawn in window name order. So for example, the default case of a zero Z-Order results in windows being drawn in name order.

More specifically:

* Windows with a negative Z-order are drawn first (in order, so -2 would be drawn before -1).

* Windows with a zero Z-order (the default) are drawn next, in name order (lower name first)

* Windows with a positive Z-order are drawn last, in Z-order sequence.

* If there are two (or more) windows with the same Z-order number, they are drawn in name order.

Note that being "drawn first" means that a window appears underneath a window which is drawn later.

see_also:
WindowArc WindowBezier WindowCreate WindowDrawImage WindowCircleOp WindowLine WindowRectOp WindowPolygon WindowGetPixel


name: UnloadPlugin
prototype: long UnloadPlugin(BSTR PluginID);
summary: Unloads an installed plugin
vb_example: UnloadPlugin "chat" UnloadPlugin "753ba7e011f3c8943a885f18"
java_example: world.UnloadPlugin ("chat"); world.UnloadPlugin ("753ba7e011f3c8943a885f18");
perl_example: $world->UnloadPlugin ("chat"); $world->UnloadPlugin ("753ba7e011f3c8943a885f18");
type_of_object: Method
see_also: IsPluginInstalled GetPluginList GetPluginInfo LoadPlugin ReloadPlugin
python_example: world.UnloadPlugin ("chat") world.UnloadPlugin ("753ba7e011f3c8943a885f18")
doc_name: plugins
lua_example: UnloadPlugin ("chat") UnloadPlugin ("753ba7e011f3c8943a885f18")
description:
Unloads (removes from MUSHclient world space) the specified plugin.

You can specify the plugin by unique ID, or by plugin name (assuming the name is unique in your list of plugins).

eg.

world.ReloadPlugin "chat"
world.ReloadPlugin "753ba7e011f3c8943a885f18"

However, a plugin cannot unload itself. That would mean the script was deleted out from under itself. If you try to work around that by having plugin A call plugin B, and plugin B unloads plugin A, you will probably get a crash. If you really want to make a "unload myself" function in a plugin, use something like DoAfterSpecial, to send the "UnloadPlugin" command to the script engine after a 1-second delay.

The check for plugin name or plugin ID is not case-sensitive.

return_value:
eNoSuchPlugin: Plugin is not currently installed
eBadParameter: Cannot unload ourselves
eOK: Unloaded OK


name: Bookmark
prototype: void Bookmark(long LineNumber, BOOL Set);
summary: Sets of clears a bookmark on the nominated line
return_value: None.
type_of_object: Method
see_also: GetLinesInBufferCount
doc_name: utility
lua_example: -- bookmark the most recently-received line Bookmark (GetLinesInBufferCount (), true)
lua_notes: The Set argument is optional. If omitted it defaults to true.
description:
Sets or clears a bookmark on any line in the output buffer (window).

The line number can be from 1 (the first line) to the number of lines in the output window. You can use "world.GetLinesInBufferCount" to find how many lines are currently in the output window. This number is different from the sequential number of the line since the world opened. 

Note that when the buffer fills up lines are discarded in batches of 100, so the last line will probably not be 5000, even if your buffer size is 5000 and you have been connected for a while. It is likely to be in the range 4900 to 4999.

If the argument "Set" is true a bookmark is set, otherwise it is cleared.

Bookmarks do not consume any extra memory (they are a flag in the existing memory allocated for a line), and you can have as many bookmarks as there are lines. Inside the client the "go to bookmark" menu operation (Ctrl+B) can be used to navigate through bookmarked lines.


name: SetTitle
prototype: void SetTitle(BSTR Title);
summary: Sets the world window title
vb_example: SetTitle "TinyMUX - admin login"
return_value: Nothing.
type_of_object: Method
see_also: Note Send SetCommand SetStatus SetMainTitle
doc_name: utils
lua_example: SetTitle "TinyMUX - admin login"
lua_notes: You can supply multiple arguments, which are concatenated together.
description:
This sets the window title (for the world window) to the nominated text. You could use this to make the tile reflect the character name, world name, or whatever you want.

Setting the title to an empty string (ie. "") will revert back to the default title line (the world name, plus connection status).


name: SetMainTitle
prototype: void SetMainTitle(BSTR Title);
summary: Sets the main output window title
vb_example: SetMainTitle "TinyMUX - admin login"
return_value: Nothing.
type_of_object: Method
see_also: Note Send SetCommand SetStatus SetTitle
doc_name: utils
lua_example: SetMainTitle "TinyMUX - admin login"
lua_notes: You can supply multiple arguments, which are concatenated together.
description:
This sets the window title (for the whole client window) to the nominated text. You could use this to make the tile reflect the character name, world name, or whatever you want.

Setting the title to an empty string (ie. "") will revert back to the default title line (the world name, plus connection status).


name: StopEvaluatingTriggers
prototype: void StopEvaluatingTriggers(BOOL AllPlugins);
summary: Stops trigger evaluation
return_value: None.
type_of_object: Method
see_also: AddTrigger GetTriggerInfo GetTriggerOption
doc_name: triggers
lua_example: StopEvaluatingTriggers (true)
description:
Call this function from a trigger script to stop trigger evaluation. This would have to be called from "send to script" (not send-to-script-after-omit), nor from a trigger script file, in order to be effective.

This causes trigger evaluation to stop, for the current line, and the current plugin. If not in a plugin, then all triggers in the "main" world trigger list stop being evaluated.

If the argument is true, then no further trigger evaluation takes place, in any further plugins.

Note that since calling a trigger script (script name in Script box) is done after all triggers are evaluated for that plugin, doing this inside a script file will be too late (for the current plugin). It has to be done in send-to-script.


