[ wxwindows-Patches-1600747 ] Fixes: Duplicate help menu in wxMac in non-English l10n

Sat Mar 1 06:05:12 PST 2008

Patches item #1600747, was opened at 2006-11-21 22:58
Message generated for change (Comment added) made by vaclavslavik
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=309863&aid=1600747&group_id=9863

Please note that this message will contain a full copy of the comment thread,
including the initial issue submission, for this request,
not just the latest update.
Category: Mac specific
Group: bug fix
Status: Closed
Resolution: Accepted
Priority: 5
Private: No
Submitted By: Andreas Jacobs (belbo)
Assigned to: Stefan Csomor (csomor)
Summary: Fixes: Duplicate help menu in wxMac in non-English l10n

Initial Comment:
When I define a help menu with a localized title under wxMac and use a non-English localization, then a second, empty, help menu is added to the menu bar as soon as I first click on the menu bar.

Reason:
wxMenuBar::MacInstallMenuBar always adds a Mac Help menu the menu bar, but if it detects, that I have defined a help menu, it moves the items of my help menu to the Mac help menu and does not display my menu. Problem: It detects my help menu only, if its title is "?", "&?" or "&Help", so it does not work with localized titles like "&Hilfe" (German) or "&Aide" (French).

My solution:
Ask the Mac menu for its (localized) title and use that for comparisons instead of "&Help" ("?" is still supported).

Changes:
- Added new UMAGetMenuTitle function to uma.h / uma.cpp that retrieves the title of any given mac menu. This function corresponds to the already existing UMASetMenuTitle.
- Added static GetMacHelpMenuTitleName function to app.cpp that is called to initialize the variable s_macHelpMenuTitleName. s_macHelpMenuTitleName was previously initialized with the constant "&Help", and is used in wxMenuBar::MacInstallMenuBar to detect, which of my menus is the help menu.
- In wxMenuBar::MacInstallMenuBar: Wrapped m_titles[i] with a call to wxStripMenuCodes, because m_titles[i] can easily contain a mnemonic character "&", while the retrieved localized help menu title in s_macHelpMenuTitleName does not

Test:
I've tested it only under Mac OS 10.4 and I cannot easily test it under Mac OS 9 or earlier.

----------------------------------------------------------------------

>Comment By: Vaclav Slavik (vaclavslavik)
Date: 2008-03-01 15:05

Message:
Logged In: YES 
user_id=80834
Originator: NO

As a workaround for 2.8, you can set wxApp::s_macHelpMenuTitleName to
localized help menu string.

I'm attaching wx-2.8 version of the patch, but I'm not comfortable
checking it in myself either.
File Added: helpmenu-2.8.patch

----------------------------------------------------------------------

Comment By: Vadim Zeitlin (vadz)
Date: 2007-03-14 01:38

Message:
Logged In: YES 
user_id=71618
Originator: NO

Thanks a lot for the nice patch and detailed explanations!

I'm not a Mac expert but the patch looks correct to me so I'm checking it
in HEAD. I will not however commit it to 2.8 on my own as I'm too afraid of
breaking something and I'd like to leave this responsibility to Stefan :-)

----------------------------------------------------------------------

Comment By: Andreas Jacobs (belbo)
Date: 2007-01-29 19:58

Message:
Logged In: YES 
user_id=1195977
Originator: YES

I'm not sure whether nice OS X citizens should use HMGetHelpMenu:
Contra:
- The example cocoa apps in /Developer/Examples/AppKit don't use
HMGetHelpMenu, but define their help menus as standard menus in their
MainMenu.nib. If I add a call to HMGetHelpMenu to their code, I get two
different help menus, one app help menu from the nib and one mac help menu.
So if cocoa apps aren't nice OS X citizens, why should carbon apps be?
- wxCocoa doesn't use HMGetHelpMenu either. Cocoa doesn't even have a
counterpart for the carbon function HMGetHelpMenu.
Pro:
- I thought HMGetHelpMenu were a deprecated function, left over to ease
porting carbon apps from OS 9 to OS X, but the Apple documentation doesn't
say so anywhere.
- There is a preliminary document from apple that talks about a system
help menu and an item that the system creates automatically inside it, so
the OS needs a way to recognize your help menu:
http://developer.apple.com/documentation/Carbon/Conceptual/ProvidingUserAssitAppleHelp/user_help_concepts/chapter_2_section_5.html
I'm puzzled and put the choice on you. This time I add a patch that uses
HMGetHelpMenu again, but you can as well use my last patch instead, maybe
removing the OS 9 specific parts.

My new patch (ghosttranslatehm.patch):
- adds UMAGetHelpMenuDontCreate to uma.h/uma.cpp, like you proposed in
ghosthelpmenu.patch
- changes wxFindMenuFromMacCommand in app.cpp to call
UMAGetHelpMenuDontCreate
- renames local variable "hm" to "helpMenuHandle" in both
wxFindMenuFromMacCommand and wxMenuBar::MacInstallMenuBar (makes code more
readable)
- recognizes the user help menu, if it is "?" or if it equals the wx
translation of "&Help" or if it equals wxApp::s_macHelpMenuTitleName. This
is the same change as in my last patch
- adds some more comments to wxMenuBar::MacInstallMenuBar for things that
took my quite a while to understand
- uses the new UMAGetHelpMenuDontCreate when cleaning the help menu. I
find this cleaning now a little easier to understand, but this is surely
disputable

Comments:
- Now the help menu title is chosen by the OS again and you cannot change
it. This has the advantages and drawbacks you mentioned in your last post,
but the most important advantage is: it conforms to Apple's standards.
- If the user app calls HMGetHelpMenu and wxMac later calls
UMAGetHelpMenuDontCreate, when UMAGetHelpMenu hasn't been called yet,
UMAGetHelpMenuDontCreate still returns a null pointer, because it cannot
know that the mac help menu has already been created. If the user app,
however, calls UMAGetHelpMenu, everything works fine later on.
- I was surprised that you told me that OS 9 is no longer supported, but
of course you know it better than me. I've searched the wx website, but
haven't found any remark telling this, and
http://wxwidgets.org/docs/platform.htm still says that OS 8.6 is supported.
Maybe someone should update that someday. :-)

File Added: ghosttranslatehm.patch

----------------------------------------------------------------------

Comment By: Dimitri (dimitrishortcut)
Date: 2007-01-15 23:33

Message:
Logged In: YES 
user_id=303951
Originator: NO

[Sorry for the late response, I'm monitoring this item but must have
missed an email notification]

Thanks for the improvements! The only thing I'm hesitant about is whether
it's a good idea to not be a nice OS-citizen (since we use our own created
help menu instead of the system's 'native' one through HMGetHelpMenu). The
native one might give free benefits later (or does now already, besides
auto-translating, which I'm not aware of). What do you think?
The biggest benefit I can see with the new patch (besides working more
automagically) is that the help menu's label can now be changed.

There's also a small change with the previous behaviour (not too bad if
you ask me, I just wanted to mention it) :
If you don't use wx translations (but do use the Contents/Resources/
method (thanks for the info!)), you now need to set the menu's label
manually. While formerly it would be auto-translated by the system.
Considering one already also sets any other menu labels manually (and most
users probably use the wx translations anyway), this is a minor point.
Another difference with previous behaviour: Any (low-level) user code that
makes use of HMGetHelpMenu currently to get access to the help menu will
now be treated to a new empty right-most help menu (so code has to be
updated).

Regarding OS 9 compilation: I think this is not needed. OS 9 support has
been dropped some time ago (the last wx to support it was tagged/branched),
and HEAD hasn't worked for a long time with OS 9. As such I think it's safe
(and cleaner) to just leave out any OS 9 changes in patches.

----------------------------------------------------------------------

Comment By: Andreas Jacobs (belbo)
Date: 2006-12-07 03:48

Message:
Logged In: YES 
user_id=1195977
Originator: YES

Good point! I agree that a help menu should not be displayed, if the
programmer does not define one. But I still want wxWidgets to automatically
recognize my help menu by its localized title. Maybe we can have both.

I've got the following idea:

Never use HMGetHelpMenu under OS X, so you never get a mac help menu. If
the user supplies a help menu, move it to the right edge, otherwise the
window menu will be the rightmost menu. There is no need to move the
individual menu items to the mac help menu under OS X.
Under OS 9, however, you always have a Mac help menu, even if you do not
call HMGetHelpMenu, if I remember it correctly. Therefore it makes sense to
move the user help menu items to the Mac help menu and not display the user
help menu.

In my new patch I have used the preprocessor macro TARGET_API_MAC_OSX to
distinguish between these two cases. If the function
wxMenuBar::MacInstallMenuBar finds a user help menu, it deals with it
almost like it does with the other menus. Only difference: it does not add
it to the menu bar immediately, but instead at the end of the function
after adding the window menu. This way the help menu is moved to the
right.

How to recognize the user help menu? In my new patch I compare each user
menu title with the current translation of "&Help". This is already defined
in wxWidgets, although it is intended for the help menu _item_, not the
help menu title. But as far as I can see, this still works, since the
translations are the same. I still support the comparison with "?" and with
wxApp::s_macHelpMenuTitleName. Note that I strip the accelerator from
wxApp::s_macHelpMenuTitleName now, because a user app might set this to its
own translation of the help menu title, and this translation will most
likely contain an accelerator. The same is true for wxWidgets translation
of "&Help".

I've made a little change to wxFindMenuFromMacCommand in app.cpp, s.t.
this function does not call HMGetHelpMenu under OS X.

How do you like that patch?

P.S. You cannot set the title of the mac help menu to an arbitrary value.
Instead the Mac chooses a language based on the system language _and_ the
set of languages that your app supports, and then sets the help menu title
accordingly. So if you want a German help menu you must tell the Mac, that
your app indeed has a German localization. For every language "xyz" that
you support, you must create a directory "xyz.lproj" in the directory
"Contents/Resources" inside the application bundle, in your case it is
"Contents/Resources/de.lproj". You can leave this directory empty, it only
has to exist.

File Added: noumahelpmenu.patch

----------------------------------------------------------------------

Comment By: Dimitri (dimitrishortcut)
Date: 2006-12-01 21:55

Message:
Logged In: YES 
user_id=303951
Originator: NO

Thanks for the clear info! I've been having similar problems with the help
menu, but I didn't even know about wxApp::s_macHelpMenuTitleName which
fixes most of my problems now.

A (still) remaining problem is that when you don't use a help menu at all,
one will be created if HMGetHelpMenu gets called (which happens as soon as
you open a menu). This can be fixed by delaying a call to that function
until it's 'certain' a help menu is wanted. Unfortunately getting the
help's label (through your GetMacHelpMenuTitleName, which gets called when
initting the app) means HMGetHelpMenu will also get called and thus a help
menu will be created unconditionally.

For now I think it would be best (but more user code needed) to set
wxApp::s_macHelpMenuTitleName to the same as your translation for the help
menu. Does that work for you? Perhaps there's another way to get the Help
menu label, so that it could also work automatically.

I've attached my changes (don't create a help menu when not needed) merged
with what remained of yours for now (stripping fixes). What do you think?

P.S. How do you change the label of the help menu? (only through
resources?) I have set my system to German, but it's still called "Help"
(unlike other applications that are restarted). Using the minimal sample I
tried changing it in code with UMASetMenuTitle, but it doesn't have any
effect on the (OS X) help menu.

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=309863&aid=1600747&group_id=9863