Help menus for Mac Studio 10.1+

Kelly Burgess kellyb at
Fri Feb 19 05:29:19 UTC 2021

Hi All,

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.$enablehelpitem(3)
Do $cinst.$addhelpitem('Online Help')
Do $cinst.$enablehelpitem(4)
Do $cinst.$addhelpitem('How To Videos on YouTube')
Do $cinst.$enablehelpitem(5)
Do $cinst.$addhelpitem('Visit Our Website')
Do $cinst.$enablehelpitem(6)
Do $cinst.$addhelpitem('Send Email to Support')
Do $cinst.$enablehelpitem(7)
If not(tIsRuntime)&(#UL=0)     ## if running in Dev mode, give access to Omnis help
  Do $cinst.$addhelpitem('Omnis Help')
  Do $cinst.$enablehelpitem(8)
End If


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
Switch pHelpMenuItemName
 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
  Do $root.$exechelp(,,helpFolderPath,,,kTrue)
End Switch


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 mailing list