QM file management functions, macro settings and resources

In macros you can call functions of special variable _qmfile to manage macro resources and other data in current QM file(s). Unavailable in exe.

 

Most functions added in QM 2.4.0, some in QM 2.4.1.

 

All functions throw error if failed, for example if macro or resource not found. With 'Get' functions, error if the resource or setting does not exist; you can use err. With 'Delete' and 'Enum' functions, not error when there are no matching resources or settings. The 'Add' functions add or replace.

 

Sub-functions cannot have resources and settings, but can use resources and settings of parent QM item.

 

Functions, parameters, examples:

 

Functions to manage macro resources

ResourceAdd($macro $resName !*data nBytes)
ResourceGet($macro $resName str&data [flags])
ResourceDelete($macro $resNameWildcard)
ResourceRename($macro $oldName $newName)
ResourceEnum($macro $resNameWildcard ARRAY(str)&aName [ARRAY(str)&aData])

 

macro - QM item whose resources are managed. Can be:

resName - resource name, eg "image:bird" or "cut.ico".

data, nBytes (ResourceAdd) - pointer to resource data, and resource size. See example.

data (ResourceGet) - str variable that receives resource data.

flags (ResourceGet): 1 - if macro does not have the resource, try to get it from a caller in the function call stack. 2 - if macro does not have the resource, but another QM item in the same QM file has a resource with this name, show a note in QM output.

resNameWildcard (ResourceDelete, ResourceEnum) - resource name. To match multiple resources, use wildcard characters as with SQLite GLOB. If "" or "*", ResourceEnum gets all.

oldName, newName (ResourceRename) - current and new resource name.

aName (ResourceEnum) - array variable that receives names of all matching resources.

aData (ResourceEnum) - optional array variable that receives data of all matching resources.

 

Examples

str s1 s2
 import image resource from file
s1.getfile("$my qm$\test.bmp")
s1.encrypt(32) ;;LZO-compress
_qmfile.ResourceAdd("Macro2193" "image:test" s1 s1.len)

 export image resource to file
_qmfile.ResourceGet("Macro2193" "image:test" s2)
err out "resource not found"; ret
s2.decrypt(32) ;;LZO-decompress
s2.setfile("$my qm$\test2.bmp")

 

Functions to manage macro settings

In macros you sometimes use various settings that must be saved somewhere. Usually programs and macros use registry (rset, rget) or files for it. Alternatively you can store macro settings in current QM file. Registry settings are specific to the computer/user. Settings stored in QM file are specific to that QM file. QM also stores some of its settings in QM file, for example toolbar positions. Note that this feature is unavailable in exe.

 

Macro settings are similar to macro resources. You can use it to store any settings and other data used in your macros. Unlike resources, settings of macros of all currently loaded QM files (main and shared) are stored in the main file. Macro settings are not used with temporary QM items (items in the Temp folder).

 

You can manage macro settings with these functions. There are no dialogs for this.

 

SettingAddB($macro $settName !*data nBytes)
SettingAddS($macro $settName $data)
SettingAddI($macro $settName data)
SettingGetB($macro $settName !*data nBytes)
$SettingGetS($macro $settName [str&data])
#SettingGetI($macro $settName)
SettingDelete($macro $settName)

 

macro - QM item whose settings are managed. Same as with the 'Resource' functions, see above.

settName - setting name. Must match case. With SettingDelete can contain wildcard characters to delete multiple.

 

The 'SettingAdd' functions add or replace setting settName of QM item macro. With SettingAddB, data is pointer to data, and nBytes is data size. With SettingAddS, data is a string value. With SettingAddI - an integer value.

 

The 'SettingGet' functions get data of setting settName of QM item macro. Function SettingGetB copies max nBytes of data to memory buffer data; error if data size is < nBytes. Function SettingGetS stores data in a str variable data and returns data as string. Function SettingGetI returns data as integer value.

 

Examples

str s1 s2; int i1 i2; POINT p1 p2
 add or update settings
s1="string value1"
_qmfile.SettingAddS("Macro2201" "name1" s1)

i1=100
_qmfile.SettingAddI("Macro2201" "name2" i1)

p1.x=10; p1.y=20
_qmfile.SettingAddB("Macro2201" "name3" &p1 sizeof(p1))

 get settings
_qmfile.SettingGetS("Macro2201" "name1" s2)
err out "setting not found"; ret
out s2
 or
out _qmfile.SettingGetS("Macro2201" "name1" _s)

i2=_qmfile.SettingGetI("Macro2201" "name2")
out i2

_qmfile.SettingGetB("Macro2201" "name3" &p2 sizeof(p2))
out F"{p2.x} {p2.y}"

 

Functions to manage QM file directly with Sqlite class

QM files are SQLite databases and can be managed with Sqlite class. For example, you can create and use your own tables. You also can get data from QM tables, but should not modify them, especially items and texts. QM currently uses these tables: items, texts, resources, xFind, xSett, xTags. Use these functions to access currently loaded QM files (main or shared). For other files instead use Sqlite.Open.

 

!*SqliteBegin([iid])
SqliteEnd()
#SqliteItemProp($macro [int&rowid] [GUID&guid])

 

SqliteBegin gives you access to the SQLite database of the currently loaded main QM file. Note that there are separate databases for each currently loaded file (the main file and shared files). You can use iid (QM item id) to access the file in which is the QM item.

 

SqliteEnd must be called when the macro finishes working with the database. Between calls to SqliteBegin and SqliteEnd the database is locked, and QM (or another macro) waits when it wants to access the database (read or write). If SqliteEnd not called, the file is locked until the thread ends.

 

SqliteItemProp gets database-specific QM item properties that you cannot get with qmitem and str.getmacro. In databases, QM items can be identified by row id or by GUID. Row id is unique in that file; it's the id column used in some tables; it's not the same as QM item id. GUID is globally unique; it's the guid column used in some tables. The macro parameter can be QM item name, id, etc, like with other functions. The function returns QM item id.

 

Examples

 get reference to database in which is macro Macro2202
Sqlite& x=_qmfile.SqliteBegin(qmitem("Macro2202")) ;;note: Sqlite& x, not Sqlite x

 now can use Sqlite functions, for example:
str sql=
 CREATE TABLE IF NOT EXISTS myTable(a INT, b TEXT);
 INSERT INTO myTable VALUES(1, 'one'),(2, 'two');
x.Exec(sql)
SqliteStatement p.Prepare(x "SELECT b FROM myTable")
rep
	if(!p.FetchRow) break
	out p.GetText(0)

 SqliteItemProp example
int iid rowid; GUID guid
iid=_qmfile.SqliteItemProp("Macro2202" rowid guid)
out "%i %i %s" iid rowid _s.FromGUID(guid)

 unlock database
_qmfile.SqliteEnd

 

Other functions

FullSave()

 

This function does the same as the Save button in QM window - applies and saves all changes. Also saves other QM settings - registry settings, toolbar positions etc. Also checkpoints currently loaded QM files, ie transfers changes collected in temporary .qml-wal files to .qml files. You can call this function for example before a custom backup. QM internally does the same when closing files, hiding QM window and in some other cases.

 

GetLoadedFiles(ARRAY(str)&aFiles)

 

Gets paths of currently loaded QM files.

 

aFiles - variable that receives path strings. The first element is the main file. Other elements - shared files. Memory databases (Temp, Deleted) are not included.

 

See also: FullSave (above).

 

Example

ARRAY(str) a
_qmfile.GetLoadedFiles(a)
out a[0] ;;main file path