Help menus for Mac Studio 10.1+
kellyb at montana.com
Fri Feb 19 05:29:19 UTC 2021
I just noticed that there's no sample app in Studio 10 that shows how you can integrate with the Help menu on the Mac. I don't see it mentioned in the What's New files, tech notes, or online documentation either. On Windows we use a regular menu class for a Help menu, but on the Mac, Help is a built-in system menu, and it includes a search mechanism for locating commands in the other menus.
Starting in Studio 10.1 there's a new osxhelp xcomp built in, and it's based on Kevin Gale's original Studio 4 component. It's simple to use.
At startup time, you instantiate an object whose class inherits from the osxhelp component, and you configure the menu.
Do $clib.$objects.oHelp.$new() Returns tHelp ## make an instance of our subclass (oHelp is a subclass of the OSXHelp component)
Do tHelp.$setup() ## set it up (oHelp.$help() will be called when the item is picked)
In your object subclass you provide a setup method to define the menu lines, and you can enable or disable them as required. The first thing you do is call the xcomp's $loadhandler method. The corresponding $unloadhandler method can be called at quit time.
# These commands mimic the mHelp menu used on Windows ## keep the two in sync.
Do $cinst.$loadhandler() ## initialize
Do $cinst.$clearhelpmenu() ## clear all items (i.e. the "What's This?" item)
Do $cinst.$addhelpitem('Help for This Window') ## add our own custom item - when picked, the $help method is called.
Do $cinst.$enablehelpitem(1) ## make sure it's enabled
Do $cinst.$addhelpitem('Help Directory for All Windows') ## add another custom item - when picked, the $help method is called.
Do $cinst.$enablehelpitem(2) ## make sure it's enabled
Do $cinst.$addhelpitem('User Guide')
Do $cinst.$addhelpitem('Online Help')
Do $cinst.$addhelpitem('How To Videos on YouTube')
Do $cinst.$addhelpitem('Visit Our Website')
Do $cinst.$addhelpitem('Send Email to Support')
If not(tIsRuntime)&(#UL=0) ## if running in Dev mode, give access to Omnis help
Do $cinst.$addhelpitem('Omnis Help')
When a Help menu item is selected, it will call the xcomp's $help method and pass the text of the chosen menu command. You override that method in your object subclass and provide the dispatching code.
# $help(menuitemname) Method called when menu item selected ## this is an override of a built-in component method
Case 'Help for This Window'
Do code method genericCode/goToHelpForWindow ($topwind().$class().$name)
Case 'Help Directory for All Windows'
Do code method genericCode/goToHelpCatalog
Case 'User Guide'
Do code method genericCode/goToUserGuide
Case 'Online Help'
Do code method genericCode/goToFAQ
Case 'How To Videos on YouTube'
Do code method genericCode/goToWebsite (videosURL)
Case 'Visit Our Website'
Do code method genericCode/goToWebsite (websiteURL)
Case 'Send Email to Support'
Do code method genericCode/goToSupportEmail
Case 'Omnis Help'
Calculate helpFolderPath as 'omnis'
# latest syntax: $exechelp(cInstName,cWindowTitle,cHelpFolder[,cDocumentName.cTopic,bIDEhelpFolder=kFalse])
# without knowing about param6, I'd had to clone the omnis help folder from the idehelp folder back to the help folder
That's all there is to it. I'd encourage you to use the osxhelp component to integrate with the Mac Help menu. It's a nice bit of polish.
More information about the omnisdev-en