Critcl wrapper for Apple Carbon Help API functions. See [L1 ] for the discussion of the Carbon Help API, and [L2 ] for discussion of how to prepare and deploy user documentation in the Apple Help format.
Kevin Walzer September 27, 2005
---
# tclAppleHelp.tcl
#
# Critcl wrapper for Apple Carbon Help API. Implements most commonly used functions.
#
# Process this file with "critcl -pkg" to build a loadable Tcl package extension.
#
# Copyright (c) 2005, WordTech Communications LLC.
# All rights reserved.
# Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
#
# Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
#
# Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
#
# Neither the name of the authors nor the names of its contributors may be used to endorse or promote products derived from this software
# without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT
# NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
# THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
#
#
package require critcl
if {![::critcl::compiling]} {error "No compiler found"}
package provide tclAppleHelp 1.0
namespace eval tclAppleHelp {
lappend ::critcl::v::compile -framework Carbon
::critcl::ccode {
#include <Carbon/Carbon.h>
#include <CoreFoundation/CoreFoundation.h>
static char *OSErrDesc(OSErr err) {
static char desc[255];
sprintf(desc, "OS Error: %d.", err);
return desc;
}
}
# ::tclAppleHelp::RegisterHelpBook
#
# This command registers a help book on application launch.
::critcl::ccommand RegisterHelpBook {ClientData ip objc objv} {
CFBundleRef myApplicationBundle;
CFURLRef myBundleURL;
FSRef myBundleRef;
OSStatus err = noErr;
myApplicationBundle = NULL;
myBundleURL = NULL;
myApplicationBundle = CFBundleGetMainBundle();
if (myApplicationBundle == NULL) {
return TCL_ERROR;
}
myBundleURL = CFBundleCopyBundleURL(myApplicationBundle);
if (myBundleURL == NULL) {
return TCL_ERROR;
}
if (!CFURLGetFSRef(myBundleURL, &myBundleRef)) {
return TCL_ERROR;
}
if (err == noErr) err = AHRegisterHelpBook(&myBundleRef);
CFRelease(myBundleURL);
return TCL_OK;
}
#::tclAppleHelp::GotoPage myBookName
#
# This command loads a help book with the specified name.
::critcl::ccommand GotoPage {ClientData ip objc objv} {
CFStringRef myBookName;
OSStatus err = noErr;
if (objc != 2) {
Tcl_WrongNumArgs(ip, 1, objv, "myBookName");
return TCL_ERROR;
}
myBookName = CFStringCreateWithCString(NULL, Tcl_GetString(objv[1]), kCFStringEncodingUTF8);
err = AHGotoPage (myBookName, NULL, NULL);
if (myBookName == NULL) {
Tcl_AppendResult(ip, "Could not load help book: ", OSErrDesc(err), NULL);
return TCL_ERROR;
}
if (err != noErr) {
Tcl_AppendResult(ip, "Could not load help book: ", OSErrDesc(err), NULL);
return TCL_ERROR;
}
if (err == noErr) {
CFRelease(myBookName);
return TCL_OK;
}
}
}