================================= ``grail.misc.winregistry`` module ================================= .. include:: ..\version.h .. include:: ref.h .. contents:: Table of Contents :backlinks: top -------- Overview -------- A utility module that treats the Win32 registry like a Python Dictionary. The purpose of this module is to make it easier to store and retrieve information from the Win32 registry. .. Warning:: Any use of the win32api [#win32api]_ may or may not experience difficulty when executed within the context of a MineSight® application. Due to an undetermined problem with the Python windows extension library. If your script will be used within a MineSight® context consider using the python ConfigParser [#python-lib-configparser]_ module or the grail.misc.iniconfigparser modules. --------------------- Terms and Definitions --------------------- It is important to distinguish between the following terms when working with this module. folder A location like \\SOFTWARE\\MineSight where other folders (keys) and values reside. keys This the Window terminology for a folder, and is also a :c:`WinRegistry` object. tag The name of a value, in the above example "win_pos" was a tag. value The value stored in a "tag" under a "key", in the above example, the geometry was a value. ------- Details ------- An example of using this class would be to store information you would like to save from one application run to another. In this case will will store the window layout. .. Python:: # ... other Tk initialization root.mainloop() registry = winregistry.WinRegistry("hkey_current_user", "\SOFTWARE\Minesight\MyApplication") geometry = root.geometry() registry["window_pos"] = geometry Later you can always retrieve that information like this, .. Python:: registry = winregistry.WinRegistry("hkey_current_user", "\SOFTWARE\Minesight\MyApplication") geometry = registry["window_pos"] Off course the key, "window_pos" may not be defined because this may the first time the application executes. In this case you would get a WinRegistryError if did what is shown above. However, if you have a default value, you can do something like this when accessing the "window_pos", .. Python:: defaultgeometry = "200x200+100+100" geometry = registry.get("window_pos", otherwise=defaultgeometry) The :f:`get()` method basically attempts to retrieve the "window_pos" value, and if it can not find it the function returns the otherwise value. In essence its equivalent to rolling your own function, .. Python:: def getgeometry(): winregistry.WinRegistry("hkey_current_user", "\SOFTWARE\Minesight\MyApplication") try: geometry = registry["window_pos"] except WinRegistryError: geometry = "200x200+100+100" return geometry There you go, the basics for working in the Window's registry. Now, what is this "hkey_current_user" stuff? In Window's terminology this is referred to as the basekey. In this module the available basekeys are described by the BASE_KEY data member. Two of the most useful ones are, * HKEY_CURRENT_USER The registry for the active user, where each user gets their own unique area to save values into. * HKEY_LOCAL_MACHINE A registry that allows you to save values for all users. Typically you will use the \\SOFTWARE folder of each of the above registry locations. An example would be generic dialogs that Grail generates. All these dialogs have there windows locations stored inside the registry under the HKEY_CURRENT_USER's \\Software\\Minesight\\Grail\\Dialog folder. The typical layout is \\SOFTWARE\\mycompany\\myapplication\\myfolders. Another note, the :c:`WinRegistry` object represents one location in the registry. In the above examples, it represented the "hkey_current_user\\SOFTWARE\\Minesight\\MyApplication" location. If you wished to retrieve the parent folder (in this case "hkey_current_user\\SOFTWARE\\Minesight") you could use the :f:`parent()` method to get a parent :c:`WinRegistry` object. Just as equally, if you where in the Minesight location you can retrieve the children (a list of other :c:`WinRegistry` objects) representing the various folders. If you want to inspect the registry on your machine go to the start menu and type: "regedit.exe". This will start the registry editor program that allows you to navigate through the folders and keys. If you execute the following source code and look into your registry using regedit.exe you will probably get a better understanding of how the registry works, .. Python:: path = 'SOFTWARE\Minesight\GRAIL\SANDBOX' r = WinRegistry('hkey_current_user', path) r['test'] = 'hey hey!' Finally, all values are treated as strings to make working with the registry easier. If you wish to store an integer you must convert that integer to a string prior to saving, and re-convert that same string to an integer after you have loaded it from the registry. --------------------- The WinRegistry Class --------------------- class :dc:`WinRegistry(basekey, key)` An abstraction on the Window's registry. This class treats the Window's registry like a dictionary. Arguments: :a:`basekey` : string On of the Window's base keys defined in the :d:`BASE_KEYS` data member also defined in this module. :a:`key` : string The location you wish to open up a :c:`WinRegistry` object inside, if the location does not exist it will be created. :df:`children()` Returns a list of children :c:`WinRegistry` objects. :df:`close()` Explicitly close a registry. Python will eventually close the registry for you as part of its automatic garbage collection. However if you are concerned about not having control on the closing "time", this method will provide you that control. :df:`deletekey(keyname)` Attempts to delete a sub-key (child). This function CAN NOT delete sub-keys (children) that also contain children. Using this method is fairly tricky. You should prefer to use the :f:`removeregistry` function in this module. Arguments: :a:`keyname` : string Name of a sub-key you wish to delete. :df:`deletetag(tag)` Removes a entry (tag-value pair) from the WinRegistry location. Argument: :a:`tag` : string Name of the tag-value pair you wish to remove. :df:`get(tag[, otherwise])` Retrieves a value if it exists, or returns the otherwise value. Arguments: :a:`tag` : string Name of the value you are looking for in the WinRegistry object. :a:`otherwise` : string A value you wish to have returned if the tag does not exist in the registry. .. Note:: The :a:`otherwise` value is *not* saved to the registry under the tag value. :df:`keys()` Returns a list of all keys in the WinRegistry object. :df:`numkeys()` Returns the number of keys in the WinRegistry object. :df:`numtags()` Returns the number of tags in this WinRegistry object. :df:`parent()` Returns the parent WinRegistry object to this object. :df:`set([**kws])` Allows you to set multiple tag-value pairs in one call. For example, .. Python:: registry.set(win_geom="200x200+100+100", win_state="minimized") Is equivalent to, :: registry["win_geom"] = "200x200+100+100" registry["win_state"] = "minimized" Arguments: :a:`kws` A dictionary of keywords. :df:`tags()` Returns a list of all tags in the WinRegistry object. --------- Exception --------- exception :de:`WinRegistryError` Defines a WinRegistry error --------- Functions --------- :df:`removeregistry(basekey, path)` Completely cleans the registry with the given path. ---- Data ---- :dd:`BASE_KEYS` A dictionary listing the values and Window's constants that can be used for the :c:`WinRegistry` object. As a user you should only know something about the keys. The values are irrelevant. ---- .. [#win32api] Mark Hammond. *Python for Windows Extension*. 8 February 2004. 9 June 2004. .. [#python-lib-configparser]_ .. [#python-lib-configparser] *Python Library*. "ConfigParser -- Configuration file parser". 30 May 2003. 9 June 2004.