Writing Extentions for gramps
<<< Previous |  | Next >>>

# Writing Tools

Users can create their own tools and add them to `gramps`. By adding the tool to the user's private plugin directory (`~/.gramps/plugins`), the tool will be automatically recognized the next time that `gramps` is started.

Unlike a report generator, a tool is allowed to modify the database. The tool is passed the current `gramps` database, the active person, and a callback function. The callback function should be called with a non-zero argument upon completion of the tool if the database has been altered.

As with filters and report generators, tools must be registered before `gramps` will understand it. The tool is registered using the `Plugins.register_tool`. This function takes four arguments.

- `The tool task` This task that executes the tool.

- `The tool category` The category in which the tool is grouped in the Tools menu and in the Tool Selection dialog.

- `The tool name` The name of the tool.

- `A text description of the tool` The description appears in the Tool Selection dialog to provide the user with a description of what the tool does.

While only the task and report name are required, it is recommended to provide all five parameters.

    import Plugins

    def tool(database,person,callback):
       ... actual code ...
       callback(1)

    Plugins.register_tool(
        task=tool,
        category="Category",
        name="Tool Name",
        description="A text descripition of the tool"
    )

Figure 3. Sample tool implementation

<<< Previous | Home | Next >>>
Writing Reports |  | Writing Import Filters