Function Naming
All the routines meant for application use are either functions with Fn'LibXL' prefixes or procedures with LibXL' prefixes. (Hard to type, but in APN, just use the Ctl+Space auto-complete feature, e.g. "SetAttr" followed by Ctrl+space.) Consistent with the underlying library, the functions are divided into Book, Sheet, Format, and Font classes, with the requirements of the object/class orientation of the library satisfied by supplying a handle to the instance of the class whose method/function is being called. The general function naming convention is Fn'LibXL'<class><verb><objects>, e.g. "Fn'LibXL'FontSetAttributes()".
Functions named this way (with one of the class names immediately following the LibXL' prefix) expect the first argument to be the handle to the corresponding class instance, e.g.
Fn'LibXL'FontSetAttributes(hfont, size=16)
HOWEVER, since 90%+ of the applications using this library are likely to use only one book (or one book at a time), it seems excessive to include "Book" in the name of each book function, as well as require that the first argument passed be a handle to that same book object. Instead, we've dropped the leading "Book" from the book class functions and made the book handle be an optional parameter that can be supplied as a trailing named parameter in cases where you have more than one book context at a time. Examples:
! no need to save book handle if dealing with only one book…
call Fn'LibXL'CreateBook(booktype)
! and no need to supply it when referencing the default book…
hSheet1 = Fn'LibXL'GetSheet(idx)
But if you are working with multiple books, then you should save the handle coming back from the CreateBook() function and pass it via the named parameter hbook to the other functions, e.g.
hbook1 = Fn'LibXL'CreateBook()
hbook2 = Fn'LibXL'CreateBook()
! add sheet to 1st book (specifying book handle by named parameter)
hsheetx = Fn'LibXL'AddSheet("sheetname",hbook=hbook1)
! add a format to 2nd book
hformat = Fn'LibXL'AddFormat(hbook=hbook2)
Remember that named parameters have to follow any unnamed (positional) parameters.
In the case of sheets, probably a slight majority of applications will be working on one sheet at a time, but for those that aren’t, most of the Sheet functions take the sheet handle as the first parameter (signaled by the function name starting with "Sheet" after the prefix). A few of the Sheet functions rely on the default (i.e. last accessed) sheet rather than requiring an explicit sheet handle, and thus they drop the "Sheet" from the name. For example:
! requires explicit sheet handle
call Fn'LibXL'SheetWriteNum(hsheet1,row,col,num)
! uses implicit (current) sheet handle
| call Fn'LibXL'WriteNum(row,col,num) |
Format and Font class functions are normally only needed in the setup of the workbook. The handles to the created objects are then used to associate Fonts with Formats and Formats with cells. So these functions mostly all require the explicit handle. Since Fonts and Formats belong to Books, you typically use Book class functions to create the class instances (e.g. Fn'LibXL'AddFont()) and then Font and Format class functions to assign attributes to them. To simplify coding, there are also some combined functions that combine the separate operations of adding the object and assigning the attributes. These combined functions typically have two parts to the main function name, e.g. "AddFormat'SetAttributes". For example:
! Separate:
! Create empty format object and add it to the default book
hformat = Fn'LibXL'AddFormat()
! Then use the object handle to set attributes to it
call LibXL'FormatSetAttributes(hformat,...)
! Combined:
hformat = Fn'LibXL'AddFormat'SetAttributes(...)
To minimize confusion between the word "format" when referring to the class, and the word "format" when referring to a numeric format specification, we abbreviate all references to the latter as "Fmt", e.g. LibXL'FormatSetNumFmt(hformat,numfmtid) sets the numeric format (fmt) identified by numfmtid for the Format class instance whose handle is hformat. (The underlying libxl library uses "format" for both, which is confusing.)
