Revived the Carbon.Help module, but implementing the MacHelp API in stead

of the defunct Balloons API. Help tags are TBD, but at least this gives
us access to the help menu.

5 files changed, 148 insertions, 269 deletions

diff --git a/Mac/Lib/Carbon/Balloons.py b/Mac/Lib/Carbon/Balloons.py
deleted file mode 100644
index 3106181..0000000
--- a/Mac/Lib/Carbon/Balloons.py
+++ /dev/null
@@ -1,66 +0,0 @@
-# Generated from 'Balloons.h'
-
-def FOUR_CHAR_CODE(x): return x
-kTopLeftTipPointsLeftVariant = 0
-kTopLeftTipPointsUpVariant = 1
-kTopRightTipPointsUpVariant = 2
-kTopRightTipPointsRightVariant = 3
-kBottomRightTipPointsRightVariant = 4
-kBottomRightTipPointsDownVariant = 5
-kBottomLeftTipPointsDownVariant = 6
-kBottomLeftTipPointsLeftVariant = 7
-kBalloonVariantCount = 8
-hmBalloonHelpVersion = 0x0002 
-kHMHelpMenuID = -16490
-kHMAboutHelpItem = 1
-kHMShowBalloonsItem = 3     
-kHMHelpID = -5696
-kBalloonWDEFID = 126   
-helpItem = 1     
-hmDefaultOptions = 0
-hmUseSubIDBit = 0
-hmAbsoluteCoordsBit = 1
-hmSaveBitsNoWindowBit = 2
-hmSaveBitsWindowBit = 3
-hmMatchInTitleBit = 4
-hmUseSubIDMask = (1 << hmUseSubIDBit)
-hmAbsoluteCoordsMask = (1 << hmAbsoluteCoordsBit)
-hmSaveBitsNoWindowMask = (1 << hmSaveBitsNoWindowBit)
-hmSaveBitsWindowMask = (1 << hmSaveBitsWindowBit)
-hmMatchInTitleMask = (1 << hmMatchInTitleBit) 
-hmUseSubID = hmUseSubIDMask
-hmAbsoluteCoords = hmAbsoluteCoordsMask
-hmSaveBitsNoWindow = hmSaveBitsNoWindowMask
-hmSaveBitsWindow = hmSaveBitsWindowMask
-hmMatchInTitle = hmMatchInTitleMask
-kHMStringItem = 1
-kHMPictItem = 2
-kHMStringResItem = 3
-kHMTEResItem = 6
-kHMSTRResItem = 7
-kHMSkipItem = 256
-kHMCompareItem = 512
-kHMNamedResourceItem = 1024
-kHMTrackCntlItem = 2048  
-khmmString = 1
-khmmPict = 2
-khmmStringRes = 3
-khmmTEHandle = 4
-khmmPictHandle = 5
-khmmTERes = 6
-khmmSTRRes = 7
-kHMEnabledItem = 0     
-kHMTETextResType = FOUR_CHAR_CODE('TEXT')
-kHMTEStyleResType = FOUR_CHAR_CODE('styl') 
-kHMDisabledItem = 1
-kHMCheckedItem = 2
-kHMOtherItem = 3
-kHMRegularWindow = 0
-kHMSaveBitsNoWindow = 1
-kHMSaveBitsWindow = 2     
-kHMMenuResType = FOUR_CHAR_CODE('hmnu')
-kHMDialogResType = FOUR_CHAR_CODE('hdlg')
-kHMWindListResType = FOUR_CHAR_CODE('hwin')
-kHMRectListResType = FOUR_CHAR_CODE('hrct')
-kHMOverrideResType = FOUR_CHAR_CODE('hovr')
-kHMFinderApplResType = FOUR_CHAR_CODE('hfdr') 
diff --git a/Mac/Lib/Carbon/MacHelp.py b/Mac/Lib/Carbon/MacHelp.py
new file mode 100644
index 0000000..a231a8d
--- /dev/null
+++ b/Mac/Lib/Carbon/MacHelp.py
@@ -0,0 +1,58 @@
+# Generated from 'MacHelp.h'
+
+def FOUR_CHAR_CODE(x): return x
+kMacHelpVersion = 0x0003
+kHMSupplyContent = 0
+kHMDisposeContent = 1
+kHMNoContent = FOUR_CHAR_CODE('none')
+kHMCFStringContent = FOUR_CHAR_CODE('cfst')
+kHMPascalStrContent = FOUR_CHAR_CODE('pstr')
+kHMStringResContent = FOUR_CHAR_CODE('str#')
+kHMTEHandleContent = FOUR_CHAR_CODE('txth')
+kHMTextResContent = FOUR_CHAR_CODE('text')
+kHMStrResContent = FOUR_CHAR_CODE('str ')
+kHMDefaultSide = 0
+kHMOutsideTopScriptAligned = 1
+kHMOutsideLeftCenterAligned = 2
+kHMOutsideBottomScriptAligned = 3
+kHMOutsideRightCenterAligned = 4
+kHMOutsideTopLeftAligned = 5
+kHMOutsideTopRightAligned = 6
+kHMOutsideLeftTopAligned = 7
+kHMOutsideLeftBottomAligned = 8
+kHMOutsideBottomLeftAligned = 9
+kHMOutsideBottomRightAligned = 10
+kHMOutsideRightTopAligned = 11
+kHMOutsideRightBottomAligned = 12
+kHMOutsideTopCenterAligned = 13
+kHMOutsideBottomCenterAligned = 14
+kHMInsideRightCenterAligned = 15
+kHMInsideLeftCenterAligned = 16
+kHMInsideBottomCenterAligned = 17
+kHMInsideTopCenterAligned = 18
+kHMInsideTopLeftCorner = 19
+kHMInsideTopRightCorner = 20
+kHMInsideBottomLeftCorner = 21
+kHMInsideBottomRightCorner = 22
+kHMAbsoluteCenterAligned = 23
+kHMTopSide = kHMOutsideTopScriptAligned
+kHMLeftSide = kHMOutsideLeftCenterAligned
+kHMBottomSide = kHMOutsideBottomScriptAligned
+kHMRightSide = kHMOutsideRightCenterAligned
+kHMTopLeftCorner = kHMOutsideTopLeftAligned
+kHMTopRightCorner = kHMOutsideTopRightAligned
+kHMLeftTopCorner = kHMOutsideLeftTopAligned
+kHMLeftBottomCorner = kHMOutsideLeftBottomAligned
+kHMBottomLeftCorner = kHMOutsideBottomLeftAligned
+kHMBottomRightCorner = kHMOutsideBottomRightAligned
+kHMRightTopCorner = kHMOutsideRightTopAligned
+kHMRightBottomCorner = kHMOutsideRightBottomAligned
+kHMContentProvided = 0
+kHMContentNotProvided = 1
+kHMContentNotProvidedDontPropagate = 2
+kHMMinimumContentIndex = 0
+kHMMaximumContentIndex = 1     
+errHMIllegalContentForMinimumState = -10980
+errHMIllegalContentForMaximumState = -10981 
+kHMIllegalContentForMinimumState = errHMIllegalContentForMinimumState
+kHelpTagEventHandlerTag = FOUR_CHAR_CODE('hevt')
diff --git a/Mac/Modules/help/_Helpmodule.c b/Mac/Modules/help/_Helpmodule.c
index 66cd7b5..328bc3a 100644
--- a/Mac/Modules/help/_Helpmodule.c
+++ b/Mac/Modules/help/_Helpmodule.c
@@ -20,264 +20,141 @@
     }} while(0)
 
 
-#include <Balloons.h>
+#ifdef WITHOUT_FRAMEWORKS
+#include <MacHelp.h>
+#else
+#include <Carbon/Carbon.h>
+#endif
 
 static PyObject *Help_Error;
 
-static PyObject *Help_HMGetHelpMenuHandle(PyObject *_self, PyObject *_args)
-{
-	PyObject *_res = NULL;
-	OSErr _err;
-	MenuRef mh;
-	if (!PyArg_ParseTuple(_args, ""))
-		return NULL;
-	_err = HMGetHelpMenuHandle(&mh);
-	if (_err != noErr) return PyMac_Error(_err);
-	_res = Py_BuildValue("O&",
-	                     MenuObj_New, mh);
-	return _res;
-}
-
-static PyObject *Help_HMRemoveBalloon(PyObject *_self, PyObject *_args)
+static PyObject *Help_HMGetHelpMenu(PyObject *_self, PyObject *_args)
 {
 	PyObject *_res = NULL;
-	OSErr _err;
+	OSStatus _err;
+	MenuRef outHelpMenu;
+	MenuItemIndex outFirstCustomItemIndex;
 	if (!PyArg_ParseTuple(_args, ""))
 		return NULL;
-	_err = HMRemoveBalloon();
+	_err = HMGetHelpMenu(&outHelpMenu,
+	                     &outFirstCustomItemIndex);
 	if (_err != noErr) return PyMac_Error(_err);
-	Py_INCREF(Py_None);
-	_res = Py_None;
-	return _res;
-}
-
-static PyObject *Help_HMIsBalloon(PyObject *_self, PyObject *_args)
-{
-	PyObject *_res = NULL;
-	Boolean _rv;
-	if (!PyArg_ParseTuple(_args, ""))
-		return NULL;
-	_rv = HMIsBalloon();
-	_res = Py_BuildValue("b",
-	                     _rv);
+	_res = Py_BuildValue("O&H",
+	                     MenuObj_New, outHelpMenu,
+	                     outFirstCustomItemIndex);
 	return _res;
 }
 
-static PyObject *Help_HMGetBalloons(PyObject *_self, PyObject *_args)
+static PyObject *Help_HMAreHelpTagsDisplayed(PyObject *_self, PyObject *_args)
 {
 	PyObject *_res = NULL;
 	Boolean _rv;
 	if (!PyArg_ParseTuple(_args, ""))
 		return NULL;
-	_rv = HMGetBalloons();
+	_rv = HMAreHelpTagsDisplayed();
 	_res = Py_BuildValue("b",
 	                     _rv);
 	return _res;
 }
 
-static PyObject *Help_HMSetBalloons(PyObject *_self, PyObject *_args)
+static PyObject *Help_HMSetHelpTagsDisplayed(PyObject *_self, PyObject *_args)
 {
 	PyObject *_res = NULL;
-	OSErr _err;
-	Boolean flag;
+	OSStatus _err;
+	Boolean inDisplayTags;
 	if (!PyArg_ParseTuple(_args, "b",
-	                      &flag))
-		return NULL;
-	_err = HMSetBalloons(flag);
-	if (_err != noErr) return PyMac_Error(_err);
-	Py_INCREF(Py_None);
-	_res = Py_None;
-	return _res;
-}
-
-static PyObject *Help_HMSetFont(PyObject *_self, PyObject *_args)
-{
-	PyObject *_res = NULL;
-	OSErr _err;
-	SInt16 font;
-	if (!PyArg_ParseTuple(_args, "h",
-	                      &font))
+	                      &inDisplayTags))
 		return NULL;
-	_err = HMSetFont(font);
+	_err = HMSetHelpTagsDisplayed(inDisplayTags);
 	if (_err != noErr) return PyMac_Error(_err);
 	Py_INCREF(Py_None);
 	_res = Py_None;
 	return _res;
 }
 
-static PyObject *Help_HMSetFontSize(PyObject *_self, PyObject *_args)
+static PyObject *Help_HMSetTagDelay(PyObject *_self, PyObject *_args)
 {
 	PyObject *_res = NULL;
-	OSErr _err;
-	UInt16 fontSize;
-	if (!PyArg_ParseTuple(_args, "H",
-	                      &fontSize))
+	OSStatus _err;
+	Duration inDelay;
+	if (!PyArg_ParseTuple(_args, "l",
+	                      &inDelay))
 		return NULL;
-	_err = HMSetFontSize(fontSize);
+	_err = HMSetTagDelay(inDelay);
 	if (_err != noErr) return PyMac_Error(_err);
 	Py_INCREF(Py_None);
 	_res = Py_None;
 	return _res;
 }
 
-static PyObject *Help_HMGetFont(PyObject *_self, PyObject *_args)
-{
-	PyObject *_res = NULL;
-	OSErr _err;
-	SInt16 font;
-	if (!PyArg_ParseTuple(_args, ""))
-		return NULL;
-	_err = HMGetFont(&font);
-	if (_err != noErr) return PyMac_Error(_err);
-	_res = Py_BuildValue("h",
-	                     font);
-	return _res;
-}
-
-static PyObject *Help_HMGetFontSize(PyObject *_self, PyObject *_args)
+static PyObject *Help_HMGetTagDelay(PyObject *_self, PyObject *_args)
 {
 	PyObject *_res = NULL;
-	OSErr _err;
-	UInt16 fontSize;
+	OSStatus _err;
+	Duration outDelay;
 	if (!PyArg_ParseTuple(_args, ""))
 		return NULL;
-	_err = HMGetFontSize(&fontSize);
-	if (_err != noErr) return PyMac_Error(_err);
-	_res = Py_BuildValue("H",
-	                     fontSize);
-	return _res;
-}
-
-static PyObject *Help_HMSetDialogResID(PyObject *_self, PyObject *_args)
-{
-	PyObject *_res = NULL;
-	OSErr _err;
-	SInt16 resID;
-	if (!PyArg_ParseTuple(_args, "h",
-	                      &resID))
-		return NULL;
-	_err = HMSetDialogResID(resID);
+	_err = HMGetTagDelay(&outDelay);
 	if (_err != noErr) return PyMac_Error(_err);
-	Py_INCREF(Py_None);
-	_res = Py_None;
+	_res = Py_BuildValue("l",
+	                     outDelay);
 	return _res;
 }
 
-static PyObject *Help_HMSetMenuResID(PyObject *_self, PyObject *_args)
+static PyObject *Help_HMSetMenuHelpFromBalloonRsrc(PyObject *_self, PyObject *_args)
 {
 	PyObject *_res = NULL;
-	OSErr _err;
-	SInt16 menuID;
-	SInt16 resID;
-	if (!PyArg_ParseTuple(_args, "hh",
-	                      &menuID,
-	                      &resID))
+	OSStatus _err;
+	MenuRef inMenu;
+	SInt16 inHmnuRsrcID;
+	if (!PyArg_ParseTuple(_args, "O&h",
+	                      MenuObj_Convert, &inMenu,
+	                      &inHmnuRsrcID))
 		return NULL;
-	_err = HMSetMenuResID(menuID,
-	                      resID);
+	_err = HMSetMenuHelpFromBalloonRsrc(inMenu,
+	                                    inHmnuRsrcID);
 	if (_err != noErr) return PyMac_Error(_err);
 	Py_INCREF(Py_None);
 	_res = Py_None;
 	return _res;
 }
 
-static PyObject *Help_HMScanTemplateItems(PyObject *_self, PyObject *_args)
+static PyObject *Help_HMSetDialogHelpFromBalloonRsrc(PyObject *_self, PyObject *_args)
 {
 	PyObject *_res = NULL;
-	OSErr _err;
-	SInt16 whichID;
-	SInt16 whichResFile;
-	ResType whichType;
-	if (!PyArg_ParseTuple(_args, "hhO&",
-	                      &whichID,
-	                      &whichResFile,
-	                      PyMac_GetOSType, &whichType))
+	OSStatus _err;
+	DialogPtr inDialog;
+	SInt16 inHdlgRsrcID;
+	SInt16 inItemStart;
+	if (!PyArg_ParseTuple(_args, "O&hh",
+	                      DlgObj_Convert, &inDialog,
+	                      &inHdlgRsrcID,
+	                      &inItemStart))
 		return NULL;
-	_err = HMScanTemplateItems(whichID,
-	                           whichResFile,
-	                           whichType);
+	_err = HMSetDialogHelpFromBalloonRsrc(inDialog,
+	                                      inHdlgRsrcID,
+	                                      inItemStart);
 	if (_err != noErr) return PyMac_Error(_err);
 	Py_INCREF(Py_None);
 	_res = Py_None;
 	return _res;
 }
 
-static PyObject *Help_HMGetDialogResID(PyObject *_self, PyObject *_args)
-{
-	PyObject *_res = NULL;
-	OSErr _err;
-	SInt16 resID;
-	if (!PyArg_ParseTuple(_args, ""))
-		return NULL;
-	_err = HMGetDialogResID(&resID);
-	if (_err != noErr) return PyMac_Error(_err);
-	_res = Py_BuildValue("h",
-	                     resID);
-	return _res;
-}
-
-static PyObject *Help_HMGetMenuResID(PyObject *_self, PyObject *_args)
-{
-	PyObject *_res = NULL;
-	OSErr _err;
-	SInt16 menuID;
-	SInt16 resID;
-	if (!PyArg_ParseTuple(_args, "h",
-	                      &menuID))
-		return NULL;
-	_err = HMGetMenuResID(menuID,
-	                      &resID);
-	if (_err != noErr) return PyMac_Error(_err);
-	_res = Py_BuildValue("h",
-	                     resID);
-	return _res;
-}
-
-static PyObject *Help_HMGetBalloonWindow(PyObject *_self, PyObject *_args)
-{
-	PyObject *_res = NULL;
-	OSErr _err;
-	WindowPtr window;
-	if (!PyArg_ParseTuple(_args, ""))
-		return NULL;
-	_err = HMGetBalloonWindow(&window);
-	if (_err != noErr) return PyMac_Error(_err);
-	_res = Py_BuildValue("O&",
-	                     WinObj_New, window);
-	return _res;
-}
-
 static PyMethodDef Help_methods[] = {
-	{"HMGetHelpMenuHandle", (PyCFunction)Help_HMGetHelpMenuHandle, 1,
-	 PyDoc_STR("() -> (MenuRef mh)")},
-	{"HMRemoveBalloon", (PyCFunction)Help_HMRemoveBalloon, 1,
-	 PyDoc_STR("() -> None")},
-	{"HMIsBalloon", (PyCFunction)Help_HMIsBalloon, 1,
-	 PyDoc_STR("() -> (Boolean _rv)")},
-	{"HMGetBalloons", (PyCFunction)Help_HMGetBalloons, 1,
+	{"HMGetHelpMenu", (PyCFunction)Help_HMGetHelpMenu, 1,
+	 PyDoc_STR("() -> (MenuRef outHelpMenu, MenuItemIndex outFirstCustomItemIndex)")},
+	{"HMAreHelpTagsDisplayed", (PyCFunction)Help_HMAreHelpTagsDisplayed, 1,
 	 PyDoc_STR("() -> (Boolean _rv)")},
-	{"HMSetBalloons", (PyCFunction)Help_HMSetBalloons, 1,
-	 PyDoc_STR("(Boolean flag) -> None")},
-	{"HMSetFont", (PyCFunction)Help_HMSetFont, 1,
-	 PyDoc_STR("(SInt16 font) -> None")},
-	{"HMSetFontSize", (PyCFunction)Help_HMSetFontSize, 1,
-	 PyDoc_STR("(UInt16 fontSize) -> None")},
-	{"HMGetFont", (PyCFunction)Help_HMGetFont, 1,
-	 PyDoc_STR("() -> (SInt16 font)")},
-	{"HMGetFontSize", (PyCFunction)Help_HMGetFontSize, 1,
-	 PyDoc_STR("() -> (UInt16 fontSize)")},
-	{"HMSetDialogResID", (PyCFunction)Help_HMSetDialogResID, 1,
-	 PyDoc_STR("(SInt16 resID) -> None")},
-	{"HMSetMenuResID", (PyCFunction)Help_HMSetMenuResID, 1,
-	 PyDoc_STR("(SInt16 menuID, SInt16 resID) -> None")},
-	{"HMScanTemplateItems", (PyCFunction)Help_HMScanTemplateItems, 1,
-	 PyDoc_STR("(SInt16 whichID, SInt16 whichResFile, ResType whichType) -> None")},
-	{"HMGetDialogResID", (PyCFunction)Help_HMGetDialogResID, 1,
-	 PyDoc_STR("() -> (SInt16 resID)")},
-	{"HMGetMenuResID", (PyCFunction)Help_HMGetMenuResID, 1,
-	 PyDoc_STR("(SInt16 menuID) -> (SInt16 resID)")},
-	{"HMGetBalloonWindow", (PyCFunction)Help_HMGetBalloonWindow, 1,
-	 PyDoc_STR("() -> (WindowPtr window)")},
+	{"HMSetHelpTagsDisplayed", (PyCFunction)Help_HMSetHelpTagsDisplayed, 1,
+	 PyDoc_STR("(Boolean inDisplayTags) -> None")},
+	{"HMSetTagDelay", (PyCFunction)Help_HMSetTagDelay, 1,
+	 PyDoc_STR("(Duration inDelay) -> None")},
+	{"HMGetTagDelay", (PyCFunction)Help_HMGetTagDelay, 1,
+	 PyDoc_STR("() -> (Duration outDelay)")},
+	{"HMSetMenuHelpFromBalloonRsrc", (PyCFunction)Help_HMSetMenuHelpFromBalloonRsrc, 1,
+	 PyDoc_STR("(MenuRef inMenu, SInt16 inHmnuRsrcID) -> None")},
+	{"HMSetDialogHelpFromBalloonRsrc", (PyCFunction)Help_HMSetDialogHelpFromBalloonRsrc, 1,
+	 PyDoc_STR("(DialogPtr inDialog, SInt16 inHdlgRsrcID, SInt16 inItemStart) -> None")},
 	{NULL, NULL, 0}
 };
 
diff --git a/Mac/Modules/help/helpscan.py b/Mac/Modules/help/helpscan.py
index 67a7e53..32a759a 100644
--- a/Mac/Modules/help/helpscan.py
+++ b/Mac/Modules/help/helpscan.py
@@ -6,7 +6,7 @@ from bgenlocations import TOOLBOXDIR, BGENDIR
 sys.path.append(BGENDIR)
 from scantools import Scanner
 
-LONG = "Balloons"
+LONG = "MacHelp"
 SHORT = "help"
 OBJECT = "NOTUSED"
 
@@ -45,15 +45,22 @@ class MyScanner(Scanner):
 
 	def makeblacklisttypes(self):
 		return [
-			"TipFunctionUPP",
-			"HMMessageRecord",
-			"HMMessageRecord_ptr",
+##			"TipFunctionUPP",
+##			"HMMessageRecord",
+##			"HMMessageRecord_ptr",
+			"HMWindowContentUPP",
+			"HMMenuTitleContentUPP",
+			"HMControlContentUPP",
+			"HMMenuItemContentUPP",
+			# For the moment
+			"HMHelpContentRec",
+			"HMHelpContentRec_ptr",
 			]
 
 	def makerepairinstructions(self):
 		return [
-			([("WindowPtr", "*", "OutMode")],
-			 [("ExistingWindowPtr", "*", "*")]),
+##			([("WindowPtr", "*", "OutMode")],
+##			 [("ExistingWindowPtr", "*", "*")]),
 			]
 			
 if __name__ == "__main__":
diff --git a/Mac/Modules/help/helpsupport.py b/Mac/Modules/help/helpsupport.py
index 96fbfe2..26fa054 100644
--- a/Mac/Modules/help/helpsupport.py
+++ b/Mac/Modules/help/helpsupport.py
@@ -6,7 +6,6 @@
 import string
 
 # Declarations that change for each manager
-MACHEADERFILE = 'Balloons.h'		# The Apple header file
 MODNAME = '_Help'				# The name of the module
 OBJECTNAME = 'UNUSED'			# The basic name of the objects used here
 KIND = 'Record'				# Usually 'Ptr' or 'Handle'
@@ -22,22 +21,26 @@ from macsupport import *
 
 # Create the type objects
 MenuRef = OpaqueByValueType("MenuRef", "MenuObj")
-
+MenuItemIndex = Type("MenuItemIndex", "H")
 
 #WindowPeek = OpaqueByValueType("WindowPeek", OBJECTPREFIX)
 
-RgnHandle = FakeType("(RgnHandle)0")
+#RgnHandle = FakeType("(RgnHandle)0")
 # XXXX Should be next, but this will break a lot of code...
 # RgnHandle = OpaqueByValueType("RgnHandle", "OptResObj")
 
-KeyMap = ArrayOutputBufferType("KeyMap")
+#KeyMap = ArrayOutputBufferType("KeyMap")
 ##MacOSEventKind = Type("MacOSEventKind", "h") # Old-style
 ##MacOSEventMask = Type("MacOSEventMask", "h") # Old-style
-EventMask = Type("EventMask", "H")
-EventKind = Type("EventKind", "H")
+#EventMask = Type("EventMask", "H")
+#EventKind = Type("EventKind", "H")
 
 includestuff = includestuff + """
-#include <%s>""" % MACHEADERFILE + """
+#ifdef WITHOUT_FRAMEWORKS
+#include <MacHelp.h>
+#else
+#include <Carbon/Carbon.h>
+#endif
 """
 
 class MyObjectDefinition(GlobalObjectDefinition):