[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
----

 #!/bin/sh
 #
 # 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.
 #
 # \
 exec critcl -pkg "$0" "$@"

 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>
 
        static char *OSErrDesc(OSErr err) {
            static char desc[255];
            sprintf(desc, "OS Error: %d.", err);
            return desc;
        }
    }
    
    # tclAppleHelp::RegisterHelpBook
    #
    # This command registers the Info.plist help book on application launch.
    
    ::critcl::cproc RegisterHelpBook {Tcl_Interp* ip} ok {
        CFBundleRef myApplicationBundle;
        CFURLRef myBundleURL;
        FSRef myBundleRef;
        Boolean result;
        OSStatus err;
        
        myApplicationBundle = CFBundleGetMainBundle();
        if (myApplicationBundle == NULL) {
            Tcl_AppendResult(ip, "CFBundleGetMainBundle failed", NULL);
            return TCL_ERROR;
        }
        myBundleURL = CFBundleCopyBundleURL(myApplicationBundle);
        if (myBundleURL == NULL) {
            Tcl_AppendResult(ip, "CFBundleCopyBundleURL failed", NULL);
            return TCL_ERROR;
        }
        result = CFURLGetFSRef(myBundleURL, &myBundleRef);
        CFRelease(myBundleURL);
        if (!result) {
            Tcl_AppendResult(ip, "CFURLGetFSRef failed", NULL);
            return TCL_ERROR;
        }
        err = AHRegisterHelpBook(&myBundleRef);
        if (err != noErr) {
            Tcl_AppendResult(ip, "Could not register help book: ",
                    OSErrDesc(err), NULL);
            return TCL_ERROR;
        }
        return TCL_OK;
    }
    
    # tclAppleHelp::GotoPage myBookName
    #
    # This command loads a help book with the specified name.
    
    ::critcl::cproc GotoPage {Tcl_Interp* ip char* myBookName} ok {
        CFStringRef myCFStrBookName;
        OSStatus err;
        
        myCFStrBookName = CFStringCreateWithCString(NULL, myBookName,
                kCFStringEncodingUTF8);
        if (myCFStrBookName == NULL) {
            Tcl_AppendResult(ip, "CFStringCreateWithCString failed", NULL);
            return TCL_ERROR;
        }
        err = AHGotoPage(myCFStrBookName, NULL, NULL);
        CFRelease(myCFStrBookName);
        if (err != noErr) {
            Tcl_AppendResult(ip, "Could not load help book: ",
                    OSErrDesc(err), NULL);
            return TCL_ERROR;
        }
        return TCL_OK;
    }
 }

----

[Category Package]