The Family Historian API (that is, Application Programming Interface) consists of a number of functions (all prefixed 'fh' in lower-case), and six objects: the Item Pointer object, the Date object, the Date Point object, the Age object, the Rich Text object and the Section object. In order to store one of these objects in a variable, you must call a function which returns a pointer of that type.

ptr = fhNewItemPtr() -- returns a Null item pointer and stores it in the variable 'ptr' 
 
ptrName = fhCreateItem("NAME", ptrInd) 
    -- creates a name item as a child of the object pointed to by ptrInd
    -- and stores a pointer to the result in the variable 'ptrName'

See the Object List for links to sections on each object.  The Function Index lists the functions broken down into categories.  Each object method or function is described in its own page, with examples of use. Hungarian notation (prefixes which indicate type) is used to describe parameters for both methods and functions. The prefixes and their meanings are given in the table below:

Optional parameters are shown in square brackets. Some functions have many optional parameters. For some functions, all parameters are optional.

Records in Family Historian are grouped together in lists - one list for each record type. Records, and the fields contained within them, are accessed using an item pointer object. To locate the first record for a given list (e.g. the first record of type 'Individual'), call the MoveToFirstRecord method for an item pointer object, passing the tag value for the record type (e.g. 'INDI' for Individual records). Thereafter, you can use the MoveNext method to move the pointer to other records in the list. If you call 'MoveNext' to move a pointer past the last record in the record list, the pointer will be set to Null (which you can test by calling the 'IsNull' method). The 'MovePrev' method moves the pointer backwards through the list, and will set the pointer to Null if you move it past the first field in the list.

Data within a record is structured in much the same way that it is structured in a Gedcom file. You can think of this structure as a tree structure. Each record has multiple fields. To access the first of these, when you have a pointer pointing to a record, call the pointer's 'MoveToFirstChildItem' method. Then call the 'MoveNext' method to move to the next field for that record - and so on. Fields in Gedcom can have subfields. These can be accessed the same way. If, for example, you have a pointer to a birth field (representing a birth event), you can call the 'MoveToFirstChildItem' method of the pointer, to access the first subfield for that field.

Further information on the Data Structure.

Various functions and methods use tags. For example, as we have seen, you specify which type of record you wish to move a pointer to, by passing the appropriate tag as the first parameter to the MoveToFirstRecord method. These tags are called Modified Gedcom Tags. They are exactly the same as ordinary Gedcom tags, except in a very small number of cases, where GEDCOM allows the same tag to be used in the same context, for fields of different types. A good example is the 'NOTE' tag. A field of this type could be either a link to a Note record; or it can simply store a textual note. Where you have two different types of field with the same tag name, in the same context, Family Historian needs to be able to disambiguate them. The rule is this: the first of the two fields (and there are never more than two), will have the normal Gedcom tag. The second of the two fields has the Gedcom tag with '2' on the end. So, for example, if ptrInd stores a pointer to an Individual record, you can move another pointer (ptr) to point to the first link to a note field, for that record, by calling ptr:MoveTo(pi,"NOTE"). But if you wanted to move the pointer to the first textual note for that record, you should call ptr:MoveTo(pi,"NOTE2") instead.

The Family Historian API allows you to add, edit or delete, any field in any record, except the header record. It also allows you to add or delete any record - and as many records as you like.

Plugins can be extremely powerful. A deliberately malicious plugin could harm your computer, just as any ordinary computer program could; so users should only ever run plugins if they know where they come from and trust whoever wrote them.

When you run a plugin, it may make all kinds of changes to your family tree database. You can undo all these change afterwards, by clicking 'Undo Plugin Updates' on the Edit menu of the main application window. If you then want to redo them, click on 'Redo Plugin Updates'. Family Historian can only undo or redo changes made to the Family Historian database itself. A plugin, might create, delete or update other files on the computer's hard disk. Family Historian cannot undo or redo these changes.

Family Historian takes care of all the consequences of any additions and deletions you may make to a Family Historian database. For example, if you add a link from a Family record to an Individual, linking the Individual as a child of the Family record, you will find that Family Historian will automatically add a link to the Individual record, linking the person back to the Family record. If you subsequently deleted this link, Family Historian would automatically delete the link back from the Family record to the Individual record.

When you delete a record, Family Historian will automatically delete all fields and subfields within that record, and all links to that record. Equally, if you delete a field, Family Historian will automatically delete all subfields of that field.

In some programming languages, which have the concept of a pointer (such as C or C++), a program will crash if you try to use a pointer to an object that has been deleted. That does not happen with the Family Historian Lua pointer objects. If you have a pointer to a field in a record, and you delete the record, the field pointer will still be a valid pointer, but its content will have become Null. If you pass a Null pointer to a function or method that expects a pointer, the function may fail if it needs the pointer to be non-Null; but the script will not crash.

If you try to delete the sex of an Individual that is a parent or spouse in a Family record, the deletion will fail. Individuals who are a parent or spouse in a Family record, must have a sex. You can however change the sex, if you wish - as long as you change it to either Male or Female.

You can of course get round this by first deleting all of a person's links as parent to family records.  Once you have done that, you can then delete their sex.

Blobs are items that represent multimedia (Pictures, Sounds, Videos, etc) which have been embedded in your Gedcom file. Embedding multimedia in Gedcom files used to be supported in Gedcom 5.5, but was dropped in Gedcom 5.5.1.  Family Historian still supports, for backwards compatibility with Gedcom 5.5, but it was rarely used even in the past, and is not recommended now.  So in practice Blobs are rarely used. Nevertheless, if necessary, they can be created (from a multimedia file) or copied, updated and deleted like other items.  The alternative to Blobs is to keep multimedia in external files (either within the project folder or not), and to store the file and path details in Media records.

Click on the name of any Family Historian function or method in a plugin, and press the F1 key to open the Help for that function or method. This is a quick and convenient way of accessing all the Help information for that function or method.

Data References (described in Understanding Data References) are used in the main application, for advanced customizations. They can also be passed as parameters to some functions and methods in the Family Historian API, and if used appropriately can help to greatly simplify what might otherwise be complex and difficult coding tasks. When Data References are used within the context of plugins, a special shortcut value '~' can be used as the first part of a Data Reference, which refers to the 'current' data item, whatever that is. For example, this function call

fhGetItemText(ptr, '~.NAME:SURNAME')

(where 'ptr' is an Item Pointer that 'points' to a particular person) will return that person's  surname.

Data References are often written enclosed within percentage signs (e.g. "%~.NAME:SURNAME%").  But they do not have to be enclosed within percentage signs when used in the context of plugins, as this example illustrates.  For more details, see Understanding Data References.

Plugins can store data on a per-machine, per-user or per-project basis.  To do so, they should call the fhGetPluginDataFileName function to get the name of a suitable file or folder to store data in.  See the fhGetPluginDataFileName for more details.