File fhUtils.lua

Functions

addFamilyAsChild (ptrIndi, ptrFam) Add a family as child to an individual
addFamilyAsSpouse (ptrIndi, ptrFam) Add existing Family as family as spouse
addWitness (ptrFact, witness, role) Add witness to existing fact
allItems (...) Interates through every field for all records of selected types, use with for loop eg
for pi in allItems('INDI') do
print (fhGetDisplayText(pi))
end
calcBirth (dtStartDate, strAge) Calculate a birth date from a given date and age If the date is not a simple date, the first date point is used for the calculation
comparestring (string1, string2, bUseSoundex) Compare String with Soundex support
createAddressList (place) Address list filtered by placename if provided with additional function to match on a starting string
createFact (ptrRecord, sTag, sPlace, dtDate, sAddress, sValue, sAge) Create new fact adding subfields
createFamilyAsChild (ptrIndi) New Family for a Child
createFamilyAsSpouse (ptrIndi) New Family as spouse for individual
createIndi (sName, sSex) Create new Individual Record
createPlaceList () Place list with additional function to match on a starting string
createResultTable () The result set provides simplifed way to create result sets.
createUpdateFact (ptrRecord, sTag, sFactLabel, sPlace, dtNewDate, sAddress, sValue, dtDate) Create or update a Fact Prompt, if there is an old fact of 'BIRT','DEAT','BAPM','MARR','BURI','CREM','CHR','CHRA' options are provided to update an existing fact, to add an additional fact, or to indicate that the user has requested a new citation for an existing fact (the function does NOT add the citation)
It is possible for the user to skip the add if required.
createUpdateItem (ptr, sTag, value) set value for fhItemPointer creating if needed and detecting the type and using the correct function
editableName (sName) Remove the Slashes from a name where it's a single word and at the end of the string.
familyList (ptr, sType) Helper for getParam, providing list of families for an individual plus an option to create a new family
getCurrentIndividual () Get first selected individual record either from the Property box or the current selections if the property box does not contain an Individual Record
getParam (sTitle, sTopMessage, fields, tButtons, shortcuts, hParent) This function allows a dynamic prompt box to be created with 5 different line types with a variety of controls for ranges and prompting.
getParamValueForDisplay (field, bFixAmp) Return display value for field
getSurname (sName) extract surname from string, try within / / if that fails get the last word
getType (object) Checks the type of the passed variable, similar to type but returns the fh type for fh Objects
helpButton (page, label) Provides iup.button object which when pressed goes to the plugin Store help page and enables UTF-8 support
indiList (surname, forename, year, minage, maxage) List of Individuals matching the critera passed in
loadOptions (defaults, scope, default) loadOptions Saves the Plugins Options as a textualized string
loadPreparedCitation () Creates a Prepared Citation object (pCite)
notSet (object) Inverse of isSet
pCite.checkRequired (self, ...) Check listed citation fields exist in the citation table
pCite.getDisplayValue (self, fieldname) Display Value of Citation field
pCite.getValue (self, fieldname) Value of Citation field
pickIndividualPrompt (values, iYear, ptrHead) Helper for getParam Takes a standard getParam result set, plus a Year and a pointer for head of household/master record
records (type) Interates through all records of selected type, use with for loop eg
for pi in records('INDI') do
print (fhGetDisplayText(pi))
end
resetOptions (defaults, scope, default) resetOptions Resets the options to the default table passed in
richTextRecordLink (ptr, text) Create record link from pointer and text
richTextReplace (s, old, new) Replace string with another in main string escaping the string for FH rich text.
saveOptions (options, scope) saveOptions Saves the Plugins Options as a textualized string
setIupDefaults () Turns on CUSTOMQUIT Message and sets the font to match the Property Box font and enables UTF-8 support, it uses fhSetStringEncoding('UTF-8') to force UTF-8
soundex (str) Convert string to soundex format
soundexall (str) Convert all words in a string to soundex format
stripCommas (s, sQuestion, sTitle, hParent) Strip Commmas Removes leading or trailing commas and consecutive commas, extra spaces before or after commas and adds a single one back in.
yes (sQuestion, sTitle, hParent) yes - prompt Yes/No prompts for yes or no


Functions

addFamilyAsChild (ptrIndi, ptrFam)
Add a family as child to an individual

Parameters:

  • ptrIndi: Pointer to Individual to add to family
  • ptrFam: Family to add child to

Return value:

    Family record pointer
addFamilyAsSpouse (ptrIndi, ptrFam)
Add existing Family as family as spouse

Parameters:

  • ptrIndi: Pointer to Individual to add to family
  • ptrFam: Family to add spouse to

Return value:

    Family record pointer
addWitness (ptrFact, witness, role)
Add witness to existing fact

Parameters:

  • ptrFact: Pointer of Fact to add Witness to
  • witness: Individual Record Pointer or String (for name only Witness)
  • role: Role for Witness

Return value:

    Family record pointer
allItems (...)
Interates through every field for all records of selected types, use with for loop eg
for pi in allItems('INDI') do
print (fhGetDisplayText(pi))
end

Parameters:

  • ...: One or more record types in list to process, leave empty for all record types.

Return value:

    single item pointer
calcBirth (dtStartDate, strAge)
Calculate a birth date from a given date and age If the date is not a simple date, the first date point is used for the calculation

Parameters:

  • dtStartDate: (fhDate object)
  • strAge: (a string defining an age in ymwd)

Return value:

    dtBirth (fhDate object), or nil
comparestring (string1, string2, bUseSoundex)
Compare String with Soundex support

Parameters:

  • string1: string
  • string2: comparison string
  • bUseSoundex: boolean - if true compare using soundex

Return value:

    boolean - true if string matched
createAddressList (place)
Address list filtered by placename if provided with additional function to match on a starting string

Parameters:

  • place: string Placename

Return values:

  1. table ipairs table of Addresses
  2. table.findFirst function to find the first matching value in the table called using table:findFirst(string)
createFact (ptrRecord, sTag, sPlace, dtDate, sAddress, sValue, sAge)
Create new fact adding subfields

Parameters:

  • ptrRecord: Pointer of record to add fact to (INDI or FAM)
  • sTag: Tag for new fact
  • sPlace: place for new fact or nil
  • dtDate: fhDate Object or nil
  • sAddress: string or nil
  • sValue: string (for attributes only) or nil
  • sAge: string Age (do not use for Family Facts)

Return value:

    fact record pointer
createFamilyAsChild (ptrIndi)
New Family for a Child

Parameters:

  • ptrIndi: Pointer to Individual to create a new family for

Return value:

    new Family Record Pointer
createFamilyAsSpouse (ptrIndi)
New Family as spouse for individual

Parameters:

  • ptrIndi: Pointer to Individual to create a new family for

Return value:

    new Family Record Pointer
createIndi (sName, sSex)
Create new Individual Record

Parameters:

  • sName: string for Name
  • sSex: string for Sex should be 'Male' or 'Female'

Return value:

    Record Pointer for new Individual
createPlaceList ()
Place list with additional function to match on a starting string

Return values:

  1. table ipairs table of place names
  2. table.findFirst function to find the first matching value in the table called using table:findFirst(string)
createResultTable ()
The result set provides simplifed way to create result sets. This result set object has the following functions. See Read More

Return value:

    Result Set Object
createUpdateFact (ptrRecord, sTag, sFactLabel, sPlace, dtNewDate, sAddress, sValue, dtDate)
Create or update a Fact Prompt, if there is an old fact of 'BIRT','DEAT','BAPM','MARR','BURI','CREM','CHR','CHRA' options are provided to update an existing fact, to add an additional fact, or to indicate that the user has requested a new citation for an existing fact (the function does NOT add the citation)
It is possible for the user to skip the add if required.

Parameters:

  • ptrRecord: Record Pointer
  • sTag: tag of item to be prompted
  • sFactLabel: string description of tag being created
  • sPlace: string New Place Value
  • dtNewDate:
  • sAddress: string New address
  • sValue: string new value for pointer (attributes only)
  • dtDate: fhDate New Date Object

Return values:

  1. pointer to fact only if skip not pressed
  2. action string showing if added or updated or a citation is required (Added/Updated/Cited)
createUpdateItem (ptr, sTag, value)
set value for fhItemPointer creating if needed and detecting the type and using the correct function

Parameters:

  • ptr: parent of item to set
  • sTag: tag of item
  • value: value to set the item to

Return value:

    Item pointer for set item
editableName (sName)
Remove the Slashes from a name where it's a single word and at the end of the string.

Parameters:

  • sName: string, Individual's name

Return value:

    sName string
familyList (ptr, sType)
Helper for getParam, providing list of families for an individual plus an option to create a new family

Parameters:

  • ptr: Individual Pointer
  • sType:
      'Parent' or 'Child' or 'FamilyAsChild' = List all Families As Child
      'Spouse' = List Families with Missing Spouse
      'FamilyAsSpouse' = List all Families with Spouse

Return value:

    table in with entries in format {ptr=fhItemPointer,label = string}
getCurrentIndividual ()
Get first selected individual record either from the Property box or the current selections if the property box does not contain an Individual Record

Return value:

    fhItemPointer, null if no record found
getParam (sTitle, sTopMessage, fields, tButtons, shortcuts, hParent)
This function allows a dynamic prompt box to be created with 5 different line types with a variety of controls for ranges and prompting. read more ...

Parameters:

  • sTitle: Window title to be displayed
  • sTopMessage: text to be displayed at the top of the prompt can be nil
  • fields: table of fields to be displayed see
  • tButtons: table of buttons to be displayed along the bottom of the prompt
  • shortcuts: table of string tables to use for the autofill on String fields
  • hParent: Parent Dialog handle

Return value:

    table fields including result table with values by tag

See also:

getParamValueForDisplay (field, bFixAmp)
Return display value for field

Parameters:

  • field: field table from getParam fields
  • bFixAmp: replace single & with && for iup.labels

Return value:

    sValue string field value as a string
getSurname (sName)
extract surname from string, try within / / if that fails get the last word

Parameters:

  • sName: string, Individual's name

Return value:

    sName string
getType (object)
Checks the type of the passed variable, similar to type but returns the fh type for fh Objects

Parameters:

  • object: object to return the type of

Return value:

    string type of object
helpButton (page, label)
Provides iup.button object which when pressed goes to the plugin Store help page and enables UTF-8 support

Parameters:

  • page: page title in the Plugin Store Help system to display
  • label: label for button, defaults to 'Help'

Return value:

    iup.button
indiList (surname, forename, year, minage, maxage)
List of Individuals matching the critera passed in

Parameters:

  • surname: surname string
  • forename: string
  • year: integer of year for which age should be computed
  • minage: minimum age to be selected
  • maxage: maximum age to be selected

Return value:

    table of values, returned table contains one table per person as follows
    label string containing display text
    ptr Individual pointer
    age integer Age in years
loadOptions (defaults, scope, default)
loadOptions Saves the Plugins Options as a textualized string

Parameters:

  • defaults:
  • scope: - Scope to use (defaults to 'CURRENT_PROJECT') other options as per fhGetPluginDataFileName
  • default: - Table of Options to use if the options file is not found

Return value:

    options - table of options
loadPreparedCitation ()
Creates a Prepared Citation object (pCite)

Return value:

    pCite Citation Object
notSet (object)
Inverse of isSet

Parameters:

  • object: object to check

Return value:

    boolean - true of object is null or string length = 0
pCite.checkRequired (self, ...)
Check listed citation fields exist in the citation table

Parameters:

  • self: pCite object function is called using pCite:checkRequired()
  • ...: list of strings containing citation meta fields

Return value:

    boolean, true if all found
pCite.getDisplayValue (self, fieldname)
Display Value of Citation field

Parameters:

  • self: pCite object function is called using pCite:getDisplayValue()
  • fieldname: string, name of field to return

Return value:

    field value as String
pCite.getValue (self, fieldname)
Value of Citation field

Parameters:

  • self: pCite object function is called using pCite:getValue()
  • fieldname: string, name of field to return

Return value:

    field value (can be fh Object or string depending in type) or nil if not found
pickIndividualPrompt (values, iYear, ptrHead)
Helper for getParam Takes a standard getParam result set, plus a Year and a pointer for head of household/master record

Parameters:

  • values: getParam Results table
  • iYear: Year
  • ptrHead: Pointer to Individual to whom the returned person may be related

Return value:

    table as follows:
    tab = -1 cancel, 1=Selected Record, 2=Create Record, 3=Name Only
    ptr = for a selected record contains the pointer
    name = for Create Record contains the name of the Record
    relation = for Create Record returns 1=Spouse, 2=Child, 3=Other , 4=Parent
    fam = pointer of family to add to for Spouse or Child, NULL for create new

See also:

records (type)
Interates through all records of selected type, use with for loop eg
for pi in records('INDI') do
print (fhGetDisplayText(pi))
end

Parameters:

  • type: Record Type string

Return value:

    single record pointer
resetOptions (defaults, scope, default)
resetOptions Resets the options to the default table passed in

Parameters:

  • defaults:
  • scope: - Scope to use (defaults to 'CURRENT_PROJECT') other options as per fhGetPluginDataFileName
  • default: - Table of Options to use if the options file is not found

Return value:

    none
richTextRecordLink (ptr, text)
Create record link from pointer and text

Parameters:

  • ptr: fhItempointer
  • text: string for title of link

Return value:

    string formated as a tFtf record link
richTextReplace (s, old, new)
Replace string with another in main string escaping the string for FH rich text.

Parameters:

  • s: replace in this string
  • old: string replace
  • new: string replacement

Return value:

    s string with replacement done
saveOptions (options, scope)
saveOptions Saves the Plugins Options as a textualized string

Parameters:

  • options: - Table of Options
  • scope: - Scope to use (defaults to 'CURRENT_PROJECT') other options as per fhGetPluginDataFileName

Return value:

    none
setIupDefaults ()
Turns on CUSTOMQUIT Message and sets the font to match the Property Box font and enables UTF-8 support, it uses fhSetStringEncoding('UTF-8') to force UTF-8
soundex (str)
Convert string to soundex format

Parameters:

  • str: string single word

Return value:

    str soundex string
soundexall (str)
Convert all words in a string to soundex format

Parameters:

  • str: string

Return value:

    str soundex string
stripCommas (s, sQuestion, sTitle, hParent)
Strip Commmas Removes leading or trailing commas and consecutive commas, extra spaces before or after commas and adds a single one back in.

Parameters:

  • s:
  • sQuestion: string, message to display
  • sTitle: string, Message box title
  • hParent: window handle for IUP parent window, if nil Family Historian main window is used

Return value:

    boolean - true if Yes pressed
yes (sQuestion, sTitle, hParent)
yes - prompt Yes/No prompts for yes or no

Parameters:

  • sQuestion: string, message to display
  • sTitle: string, Message box title
  • hParent: window handle for IUP parent window, if nil Family Historian main window is used

Return value:

    boolean - true if Yes pressed

Valid XHTML 1.0!