282 lines
4.0 KiB
HTML
282 lines
4.0 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
|
|
<HTML
|
|
><HEAD
|
|
><TITLE
|
|
>Writing Tools</TITLE
|
|
><META
|
|
NAME="GENERATOR"
|
|
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
|
|
"><LINK
|
|
REL="HOME"
|
|
TITLE="Writing Extentions for gramps"
|
|
HREF="t1.html"><LINK
|
|
REL="PREVIOUS"
|
|
TITLE="Writing Reports"
|
|
HREF="x83.html"><LINK
|
|
REL="NEXT"
|
|
TITLE="Writing Import Filters"
|
|
HREF="x162.html"></HEAD
|
|
><BODY
|
|
CLASS="SECT1"
|
|
BGCOLOR="#FFFFFF"
|
|
TEXT="#000000"
|
|
LINK="#0000FF"
|
|
VLINK="#840084"
|
|
ALINK="#0000FF"
|
|
><DIV
|
|
CLASS="NAVHEADER"
|
|
><TABLE
|
|
SUMMARY="Header navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TH
|
|
COLSPAN="3"
|
|
ALIGN="center"
|
|
>Writing Extentions for gramps</TH
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="left"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="x83.html"
|
|
ACCESSKEY="P"
|
|
><<< Previous</A
|
|
></TD
|
|
><TD
|
|
WIDTH="80%"
|
|
ALIGN="center"
|
|
VALIGN="bottom"
|
|
></TD
|
|
><TD
|
|
WIDTH="10%"
|
|
ALIGN="right"
|
|
VALIGN="bottom"
|
|
><A
|
|
HREF="x162.html"
|
|
ACCESSKEY="N"
|
|
>Next >>></A
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"></DIV
|
|
><DIV
|
|
CLASS="SECT1"
|
|
><H1
|
|
CLASS="SECT1"
|
|
><A
|
|
NAME="writingtools">Writing Tools</H1
|
|
>
|
|
<P
|
|
> Users can create their own tools and add them to
|
|
<TT
|
|
CLASS="APPLICATION"
|
|
>gramps</TT
|
|
>. By adding the tool to the
|
|
user's private plugin directory (<TT
|
|
CLASS="FILENAME"
|
|
>~/.gramps/plugins</TT
|
|
>), the tool will be
|
|
automatically recognized the next time that
|
|
<TT
|
|
CLASS="APPLICATION"
|
|
>gramps</TT
|
|
> is started.
|
|
</P
|
|
>
|
|
<P
|
|
> Unlike a report generator, a tool is allowed to modify the
|
|
database. The tool is passed the current
|
|
<TT
|
|
CLASS="APPLICATION"
|
|
>gramps</TT
|
|
> 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.
|
|
</P
|
|
>
|
|
<P
|
|
> As with filters and report generators, tools must be registered
|
|
before <TT
|
|
CLASS="APPLICATION"
|
|
>gramps</TT
|
|
> will understand it. The
|
|
tool is registered using the
|
|
<TT
|
|
CLASS="FUNCTION"
|
|
>Plugins.register_tool</TT
|
|
>. This function takes
|
|
four arguments.
|
|
</P
|
|
>
|
|
<P
|
|
></P
|
|
><UL
|
|
><LI
|
|
> <P
|
|
> <TT
|
|
CLASS="GUILABEL"
|
|
><B
|
|
>The tool task</B
|
|
></TT
|
|
> This task
|
|
that executes the tool.
|
|
</P
|
|
>
|
|
</LI
|
|
><LI
|
|
> <P
|
|
> <TT
|
|
CLASS="GUILABEL"
|
|
><B
|
|
>The tool category</B
|
|
></TT
|
|
> The category in which
|
|
the tool is grouped in the
|
|
<B
|
|
CLASS="GUIMENU"
|
|
>Tools</B
|
|
> menu and in
|
|
the <SPAN
|
|
CLASS="INTERFACE"
|
|
>Tool Selection</SPAN
|
|
> dialog.
|
|
</P
|
|
>
|
|
</LI
|
|
><LI
|
|
> <P
|
|
> <TT
|
|
CLASS="GUILABEL"
|
|
><B
|
|
>The tool name</B
|
|
></TT
|
|
>
|
|
The name of the tool.
|
|
</P
|
|
>
|
|
</LI
|
|
><LI
|
|
> <P
|
|
> <TT
|
|
CLASS="GUILABEL"
|
|
><B
|
|
>A text description of the tool</B
|
|
></TT
|
|
> The
|
|
description appears in the Tool Selection dialog to provide
|
|
the user with a description of what the tool does.
|
|
</P
|
|
>
|
|
</LI
|
|
></UL
|
|
>
|
|
<P
|
|
> While only the task and report name are required, it is
|
|
recommended to provide all five parameters.
|
|
</P
|
|
>
|
|
<DIV
|
|
CLASS="FIGURE"
|
|
><A
|
|
NAME="toolsrc">
|
|
<TABLE
|
|
BORDER="0"
|
|
BGCOLOR="#E0E0E0"
|
|
WIDTH="100%"
|
|
><TR
|
|
><TD
|
|
><PRE
|
|
CLASS="PROGRAMLISTING"
|
|
> 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"
|
|
)
|
|
</PRE
|
|
></TD
|
|
></TR
|
|
></TABLE
|
|
>
|
|
<P
|
|
><B
|
|
>Figure 3. Sample tool implementation</B
|
|
></P
|
|
></DIV
|
|
>
|
|
</DIV
|
|
><DIV
|
|
CLASS="NAVFOOTER"
|
|
><HR
|
|
ALIGN="LEFT"
|
|
WIDTH="100%"><TABLE
|
|
SUMMARY="Footer navigation table"
|
|
WIDTH="100%"
|
|
BORDER="0"
|
|
CELLPADDING="0"
|
|
CELLSPACING="0"
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="x83.html"
|
|
ACCESSKEY="P"
|
|
><<< Previous</A
|
|
></TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="t1.html"
|
|
ACCESSKEY="H"
|
|
>Home</A
|
|
></TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
><A
|
|
HREF="x162.html"
|
|
ACCESSKEY="N"
|
|
>Next >>></A
|
|
></TD
|
|
></TR
|
|
><TR
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="left"
|
|
VALIGN="top"
|
|
>Writing Reports</TD
|
|
><TD
|
|
WIDTH="34%"
|
|
ALIGN="center"
|
|
VALIGN="top"
|
|
> </TD
|
|
><TD
|
|
WIDTH="33%"
|
|
ALIGN="right"
|
|
VALIGN="top"
|
|
>Writing Import Filters</TD
|
|
></TR
|
|
></TABLE
|
|
></DIV
|
|
></BODY
|
|
></HTML
|
|
> |