[Critcl] wrapper for Apple Carbon Help API functions. See [http://developer.apple.com/documentation/Carbon/Reference/Apple_Help/index.html] for the discussion of the Carbon Help API, and [http://developer.apple.com/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/index.html] 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;
	}
    }
 }

----

[Category Package]