4. Hooks and host methods

A hook is a method in your database that Foundation calls at a defined moment, by name, with EXECUTE METHOD. If the method is absent Foundation does something sensible. If present, it must be shared (the "Shared by components and host database" attribute), or the call fails. Foundation creates each hook it needs on first startup in an interpreted host, with the expected parameters and a comment saying what it is for, so the easiest way to get one is to let Foundation make it and then fill it in. Foundation Product Sales has a working copy of every one.

A host method (Fnd_Host_*) is the same mechanism used the other way: a small method Foundation needs you to have because a component cannot do the thing itself. Foundation creates these too and you normally never edit them.

Shell

Hook	Called	Use it to
`Fnd_Hook_Shell_Setup`	once at startup, before anything is shown	set the database name, version, copyright and URL with `Fnd_Gen_SetDatabaseInfo`; the About box history with `Fnd_Art_VersionHistory`
`Fnd_Hook_Shell_Startup`	after setup, while the startup dialog shows	your own startup code: number formats, defaults, opening a first window
`Fnd_Hook_Shell_InitPlugins`	at startup, single-user and server	activate plugins
`Fnd_Hook_Shell_VirtualStructure`	at startup	give tables and fields the names the user should see (`Fnd_VS_*`)
`Fnd_Hook_Shell_NavPalette`	each time the palette is built	`Fnd_Nav_AddButtonTable(->[Table]; …)` per table, `Fnd_Nav_AddButtonMethod("method"; "label"; …)` per command, then `Fnd_Nav_Display`
`Fnd_Hook_Shell_OpenTable`	before the Open Table dialog	restrict or reorder the tables offered
`Fnd_Hook_Shell_Find`	before the Find dialog	`Fnd_Find_AddItem` the fields to offer for the current table
`Fnd_Hook_Shell_Sort`	before the Sort dialog	the fields to offer, likewise
`Fnd_Hook_Shell_QueryEditor`	from the Query Editor command	display a query editor for the current table; Foundation first syncs the list window's selection
`Fnd_Hook_Shell_ModifyRecords`	from the Modify Records command	show your own batch-change dialog
`Fnd_Hook_Shell_Print`	from Print	your own print dialog or report
`Fnd_Hook_Shell_Administration`	from Administration	your own admin dialog
`Fnd_Hook_Shell_SpecialFunctions`	from Special Functions	`Fnd_List_AddItem` your own commands to its list
`Fnd_Hook_Shell_Quit`	just before `QUIT 4D`	last-moment cleanup; return True to allow the quit, False to abort it

Records and record windows

Hook	Called	Use it to
`Fnd_Hook_IO_DisplayTable`	just before a list window opens	window title, type and size for a table (`Fnd_Wnd_*`), your process object's init
`Fnd_Hook_IO_DisplayRecord`	just before a record window opens	the same for a record: FPS sets "Invoice: 1234" here, and a fixed window for `[CompanyInfo]`
`Fnd_Hook_IO_InputFormMethod`	on every event of every input form	behaviour common to all your record windows
`Fnd_Hook_IO_OutputFormMethod`	on every event of a classic output form	likewise for classic list forms
`Fnd_Hook_IO_InputFormButton`	when an inherited button (Save, Cancel, First, Next…) is clicked, with the button name in lower case	validate before Save; return False to stop the default action
`Fnd_Hook_IO_SelectionChanged`	whenever Foundation changes the current table's selection (find, sort, show all)	react to the new selection; `Fnd_Gen_CurrentTable` says which table
`Fnd_Hook_Rec_New`	when the user asks for a new record, with a pointer to the table	return True to let Foundation create it, False to handle it yourself
`Fnd_Hook_Rec_Delete`	before Foundation deletes; the `UserSet` set holds the records	return True for Foundation's warning and delete, False to handle it yourself

Lists, menus, output

Hook	Called	Use it to
`Fnd_Hook_List_SetEditableLists`	at startup	name the 4D lists the user may edit in the list editor
`Fnd_Hook_Menu_UpdateMenuBar`	each time Foundation rebuilds the menu bar	enable, disable or add menu items
`Fnd_Hook_Out_RowStyle`	for every row a list window draws	return font, colour and style for the row from its record (chapter 5)
`Fnd_Hook_Out_ContextMenu`	on a right-click in a list window	add your own items to the menu (chapter 5)
`Fnd_Hook_SqNo_SetIDField`	when sequence numbers need a table's key field	return a pointer to it when it is not the first field

Host methods

Method	Foundation uses it to
`Fnd_Host_ExecuteFormula`	run a formula text in the host's context (the `OK` variable, your methods)
`Fnd_Host_GetIntegerValue`	read a host variable by name
`Fnd_Host_GetFormProperties`	read the size of one of your forms
`Fnd_Host_ListToArray`, `Fnd_Host_ArrayToList`, `Fnd_Host_SaveList`	read, write and persist the host's 4D lists: localisation, editable lists, preferences
`Fnd_Host_GetPictureFromLibrary`	fetch a picture from the host's library by name
`Fnd_Host_IO_DisplayDialog`	show one of the host's dialogs
`Fnd_Host_Tlbr_ButtonClck`, `Fnd_Host_Tlbr_SetBtnPict`, `Fnd_Host_Tlbr_SetMessage`	toolbar callbacks for the classic output form

Each of these is a few lines. If you delete one, delete its Compiler_Fnd_Host_* method too; Foundation recreates both.

When a hook's signature changes

Foundation compares an existing hook's declared parameters with the ones it now passes (interpreted hosts only) and reports a mismatch at startup rather than rewriting your code. Release/UPGRADING.md lists every such change by release.