+ initial version of GUI help support

rtl/os2/pmhelp.pas

@@ -0,0 +1,502 @@
+{
+    $Id$
+    This file is part of the Free Pascal run time library.
+    Copyright (c) 2002 by Yuri Prokushev ([email protected]).
+
+    OS/2 Presentation Manager Information Presentation Facility,
+    Help Manager declarations.
+
+    See the file COPYING.FPC, included in this distribution,
+    for details about the copyright.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
+
+ **********************************************************************}
+
+{Warning: This code is alfa. Future versions
+ of this unit might not be compatible.}
+ 
+unit pmhelp;
+
+interface
+
+{$MODE OBJFPC}
+
+uses
+  os2def,
+  pmbitmap,
+  pmwin;
+
+resourcestring  
+  msg_failedtodisplay='Failed to display help panel.';
+  msg_failedtoload='Failed to load help manager.';
+  
+//************************************************************************/
+//* HelpSubTable entry structure                                         */
+//************************************************************************/
+type
+  HelpSubTable=Word;
+  PHelpSubTable=^HelpSubTable;
+    
+//************************************************************************/
+//* HelpTable entry structure                                            */
+//*                                                                      */
+//*  Pack the structure HELPTABLE so that it is identical in the 32-Bit  */
+//*  and 16-Bit world.  We have to do this because the HelpTable can     */
+//*  reside either in memory or in the application's resources.          */
+//************************************************************************/
+type
+{$PACKRECORDS 2}
+  PHelpTable=^HelpTable;
+  HelpTable=record
+    idAppWindow: Word;
+    phstHelpSubTable: PHelpSubTable;
+    idExtPanel: Word;
+  End;
+   
+   
+//************************************************************************/
+//* IPF Initialization Structure used on the                             */
+//* WinCreateHelpInstance() call.                                        */
+//************************************************************************/
+
+type
+   PHelpInit=^HelpInit;
+   HelpInit=record
+     cb: cardinal;
+     ulReturnCode: cardinal;
+     pszTutorialName: PChar;
+     phtHelpTable: PHelpTable;
+     hmodHelpTableModule: cardinal;
+     hmodAccelActionBarModule: cardinal;
+     idAccelTable: cardinal;
+     idActionBar: cardinal;
+     pszHelpWindowTitle: PChar;
+     fShowPanelId: cardinal;
+     pszHelpLibraryName: PChar;
+   End;
+   
+//************************************************************************/
+//* Search parent chain indicator for HM_SET_ACTIVE_WINDOW message.      */
+//************************************************************************/
+   
+const
+  HWnd_Parent = 0;
+  
+//************************************************************************/
+//* Constants used to define whether user wants to display panel using   */
+//* panel number or panel name.                                          */
+//************************************************************************/
+
+const
+  HM_ResourceID = 0;
+  HM_PanelName  = 1;
+
+  HMPanelType_Number  =0;
+  HMPanelType_Name    =1;
+     
+//************************************************************************/ 
+//* Constants used to define how the panel IDs are displayed on          */
+//* help panels.                                                         */
+//************************************************************************/
+
+const
+  CMIC_Hide_Panel_ID        =$0000;
+  CMIC_Show_Panel_ID        =$0001;
+  CMIC_Toggle_Panel_ID      =$0002;
+
+
+//************************************************************************/
+//* IPF message base.                                                    */
+//************************************************************************/
+const
+  HM_Msg_Base               =$0220;
+
+//************************************************************************/
+//* Messages applications can send to the IPF.                           */
+//************************************************************************/
+const
+  HM_Dismiss_Window              =HM_Msg_Base+$0001;
+  HM_Display_Help                =HM_Msg_Base+$0002;
+  HM_Ext_Help                    =HM_Msg_Base+$0003;
+  HM_General_Help                =HM_Ext_Help;
+  HM_Set_Active_Window           =HM_Msg_Base+$0004;
+  HM_Load_Help_Table             =HM_Msg_Base+$0005;
+  HM_Create_Help_Table           =HM_Msg_Base+$0006;
+  HM_Set_Help_Window_Title       =HM_Msg_Base+$0007;
+  HM_Set_Show_Panel_ID           =HM_Msg_Base+$0008;
+  HM_Replace_Help_For_Help       =HM_Msg_Base+$0009;
+  HM_Replace_Using_Help          =HM_Replace_Help_For_Help;
+  HM_Help_Index                  =HM_Msg_Base+$000a;
+  HM_Help_Contents               =HM_Msg_Base+$000b;
+  HM_Keys_Help                   =HM_Msg_Base+$000c;
+  HM_Set_Help_Library_Name       =HM_Msg_Base+$000d;
+
+  HM_Set_OBJCOM_Window           =HM_Msg_Base+$0018;
+  HM_Upadte_OBJCOM_Window_Chain  =HM_Msg_Base+$0019;
+  HM_Query_DDF_Data              =HM_Msg_Base+$001a;
+  HM_Invalidate_DDF_Data         =HM_Msg_Base+$001b;
+  HM_Query                       =HM_Msg_Base+$001c;
+  HM_Set_CoverPage_Size          =HM_Msg_Base+$001d;
+
+//************************************************************************/
+//* Constants used to query the info from IPF in HM_QUERY message        */
+//************************************************************************/
+   
+//* Hi word in lParam 1 */
+const
+  HMQW_COVERPAGE           =$0001;
+  HMQW_INDEX               =$0002;
+  HMQW_TOC                 =$0003;
+  HMQW_SEARCH              =$0004;
+  HMQW_VIEWPAGES           =$0005;
+  HMQW_LIBRARY             =$0006;
+  HMQW_VIEWPORT            =$0007;
+  HMQW_OBJCOM_WINDOW       =$0008;
+  HMQW_INSTANCE            =$0009;
+  HMQW_ACTIVEVIEWPORT      =$000a;
+  CONTROL_SELECTED         =$000b;
+
+  HMQW_GROUP_VIEWPORT      =$00f1;
+  HMQW_RES_VIEWPORT        =$00f2;
+  USERDATA                 =$00f3;
+
+//* Lo word in lParam1 of HMQW_VIEWPORT */
+  HMQVP_NUMBER             =$0001;
+  HMQVP_NAME               =$0002;
+  HMQVP_GROUP              =$0003;
+
+//************************************************************************/
+//* Predefined Control IDs                                               */
+//************************************************************************/
+   
+const
+  CTRL_PREVIOUS_ID             =$0001;
+  CTRL_SEARCH_ID               =$0002;
+  CTRL_PRINT_ID                =$0003;
+  CTRL_INDEX_ID                =$0004;
+  CTRL_CONTENTS_ID             =$0005;
+  CTRL_BACK_ID                 =$0006;
+  CTRL_FORWARD_ID              =$0007;
+  CTRL_TUTORIAL_ID             =$00FF;
+
+  CTRL_USER_ID_BASE            =257;
+
+//************************************************************************/
+//* Messages the IPF sends to the applications active window             */
+//* as defined by the IPF.                                               */
+//************************************************************************/
+   
+const
+  HM_ERROR                       =HM_Msg_Base+$000e;
+  HM_HELPSUBITEM_NOT_FOUND       =HM_Msg_Base+$000f;
+  HM_QUERY_KEYS_HELP             =HM_Msg_Base+$0010;
+  HM_TUTORIAL                    =HM_Msg_Base+$0011;
+  HM_EXT_HELP_UNDEFINED          =HM_Msg_Base+$0012;
+  HM_GENERAL_HELP_UNDEFINED      =HM_EXT_HELP_UNDEFINED;
+  HM_ACTIONBAR_COMMAND           =HM_Msg_Base+$0013;
+  HM_INFORM                      =HM_Msg_Base+$0014;
+  HM_NOTIFY                      =HM_Msg_Base+$0022;
+  HM_SET_USERDATA                =HM_Msg_Base+$0023;
+  HM_CONTROL                     =HM_Msg_Base+$0024;
+
+//**********************************************************************/
+//* notify information for HM_NOTIFY                                   */
+//**********************************************************************/
+const
+  OPEN_COVERPAGE        =$0001;
+  OPEN_PAGE             =$0002;
+  SWAP_PAGE             =$0003;
+  OPEN_TOC              =$0004;
+  OPEN_INDEX            =$0005;
+  OPEN_HISTORY          =$0006;
+  OPEN_SEARCH_HIT_LIST  =$0007;
+  OPEN_LIBRARY          =$0008;
+  HELP_REQUESTED        =$0009;
+
+//**********************************************************************/
+//* HMERR_NO_FRAME_WND_IN_CHAIN - There is no frame window in the      */
+//* window chain from which to find or set the associated help         */
+//* instance.                                                          */
+//**********************************************************************/
+const
+  HMERR_NO_FRAME_WND_IN_CHAIN                =$00001001;
+
+//*********************************************************************/
+//* HMERR_INVALID_ASSOC_APP_WND - The application window handle       */
+//* specified on the WinAssociateHelpInstance() call is not a valid   */
+//* window handle.                                                    */
+//*********************************************************************/
+const
+  HMERR_INVALID_ASSOC_APP_WND                =$00001002;
+
+//**********************************************************************/
+//* HMERR_INVALID_ASSOC_HELP_INST - The help instance handle specified */
+//* on the WinAssociateHelpInstance() call is not a valid              */
+//* window handle.                                                     */
+//**********************************************************************/
+const
+  HMERR_INVALID_ASSOC_HELP_INST              =$00001003;
+
+//**********************************************************************/
+//* HMERR_INVALID_DESTROY_HELP_INST - The window handle specified      */
+//* as the help instance to destroy is not of the help instance class. */
+//**********************************************************************/
+const
+  HMERR_INVALID_DESTROY_HELP_INST            =$00001004;
+
+//**********************************************************************/
+//* HMERR_NO_HELP_INST_IN_CHAIN - The parent or owner chain of the     */
+//* application window specified does not have a help instance         */
+//* associated with it.                                                */
+//**********************************************************************/
+const
+  HMERR_NO_HELP_INST_IN_CHAIN                =$00001005;
+
+//**********************************************************************/
+//* HMERR_INVALID_HELP_INSTANCE_HDL - The handle specified to be a     */
+//* help instance does not have the class name of a IPF                */
+//* help instance.                                                     */
+//**********************************************************************/
+const
+  HMERR_INVALID_HELP_INSTANCE_HDL            =$00001006;
+
+//*********************************************************************/
+//* HMERR_INVALID_QUERY_APP_WND - The application window specified on */
+//* a WinQueryHelpInstance() call is not a valid window handle.       */
+//*********************************************************************/
+const
+  HMERR_INVALID_QUERY_APP_WND                =$00001007;
+
+//*********************************************************************/
+//* HMERR_HELP_INST_CALLED_INVALID -  The handle of the help instance */
+//* specified on an API call to the IPF does not have the             */
+//* class name of an IPF help instance.                               */
+//*********************************************************************/
+const
+  HMERR_HELP_INST_CALLED_INVALID             =$00001008;
+
+  HMERR_HELPTABLE_UNDEFINE                   =$00001009;
+  HMERR_HELP_INSTANCE_UNDEFINE               =$0000100a;
+  HMERR_HELPITEM_NOT_FOUND                   =$0000100b;
+  HMERR_INVALID_HELPSUBITEM_SIZE             =$0000100c;
+  HMERR_HELPSUBITEM_NOT_FOUND                =$0000100d;
+
+//*********************************************************************/
+//* HMERR_INDEX_NOT_FOUND - No index in library file.                 */
+//*********************************************************************/
+const
+  HMERR_INDEX_NOT_FOUND                      =$00002001;
+
+//**********************************************************************/
+//* HMERR_CONTENT_NOT_FOUND - Library file does not have any contents. */
+//**********************************************************************/
+const
+  HMERR_CONTENT_NOT_FOUND                    =$00002002;
+
+//*********************************************************************/
+//* HMERR_OPEN_LIB_FILE     - Cannot open library file                */
+//*********************************************************************/
+const
+  HMERR_OPEN_LIB_FILE                        =$00002003;
+
+//*********************************************************************/
+//* HMERR_READ_LIB_FILE     - Cannot read library file                */
+//*********************************************************************/
+const
+  HMERR_READ_LIB_FILE                        =$00002004;
+
+//*********************************************************************/
+//* HMERR_CLOSE_LIB_FILE    - Cannot close library file               */
+//*********************************************************************/
+const
+  HMERR_CLOSE_LIB_FILE                       =$00002005;
+
+//*********************************************************************/
+//* HMERR_INVALID_LIB_FILE  - Improper library file provided          */
+//*********************************************************************/
+const
+  HMERR_INVALID_LIB_FILE                     =$00002006;
+
+//************************************************************************/
+//* HMERR_NO_MEMORY - Unable to allocate the requested amount of memory. */
+//************************************************************************/
+const
+  HMERR_NO_MEMORY                            =$00002007;
+
+//*********************************************************************/
+//* HMERR_ALLOCATE_SEGMENT - Unable                                   */
+//* to allocate a segment of memory for memory allocation requested   */
+//* from the IPF.                                                     */
+//*********************************************************************/
+const
+  HMERR_ALLOCATE_SEGMENT                     =$00002008;
+
+//*********************************************************************/
+//* HMERR_FREE_MEMORY - Unable to free allocated  memory              */
+//*********************************************************************/
+const
+  HMERR_FREE_MEMORY                          =$00002009;
+
+//*********************************************************************/
+//* HMERR_PANEL_NOT_FOUND  - Unable                                   */
+//* to find a help panel requested to help manager                    */
+//*********************************************************************/
+const
+  HMERR_PANEL_NOT_FOUND                      =$00002010;
+
+//*********************************************************************/
+//* HMERR_DATABASE_NOT_OPEN - Unable to read the unopened database    */
+//*********************************************************************/
+const
+  HMERR_DATABASE_NOT_OPEN                    =$00002011;
+
+//*********************************************************************/
+//* HMERR_DDL_ERROR - Unable to load resource dll                     */
+//*********************************************************************/
+const
+  HMERR_LOAD_DLL                              =$00002013;
+
+//********************************************************************/
+//* AC Viewport stucture definitions                                 */
+//********************************************************************/
+type
+  PACVP=^ACVP;
+  ACVP=record
+    cb: cardinal;
+    hAB: HAB;
+    hmq: HMQ;
+    ObjectID: cardinal;         // object identifier
+    hWndParent: HWND;        // IPF viewport client handle
+    hWndOwner: HWND;         // IPF viewport client handle
+    hWndACVP: HWND;          // applications frame window hwnd
+  end;
+
+//*******************************************************************/
+//* Define Handle to DDF                                            */
+//*******************************************************************/
+Type
+  HDDF=pointer;
+
+// DdfHyperText Flags
+const
+  REFERENCE_BY_ID     =0;
+  REFERENCE_BY_RES    =1;
+
+// DdfBeginList formatting flags 
+  HMBT_NONE           =1;
+  HMBT_ALL            =2;
+  HMBT_FIT            =3;
+
+  HMLS_SINGLELINE     =1;
+  HMLS_DOUBLELINE     =2;
+
+// DdfBitmap alignment flags
+  ART_RUNIN           =$10;
+  ART_LEFT            =$01;
+  ART_RIGHT           =$02;
+  ART_CENTER          =$04;
+
+// DdfSetColor Color Flag
+  CLR_UNCHANGED       =-6;
+
+//*******************************************************************/
+// error codes returned by DDF API functions                        */
+//*******************************************************************/
+const
+  HMERR_DDF_MEMORY                  =$3001;
+  HMERR_DDF_ALIGN_TYPE              =$3002;
+  HMERR_DDF_BACKCOLOR               =$3003;
+  HMERR_DDF_FORECOLOR               =$3004;
+  HMERR_DDF_FONTSTYLE               =$3005;
+  HMERR_DDF_REFTYPE                 =$3006;
+  HMERR_DDF_LIST_UNCLOSED           =$3007;
+  HMERR_DDF_LIST_UNINITIALIZED      =$3008;
+  HMERR_DDF_LIST_BREAKTYPE          =$3009;
+  HMERR_DDF_LIST_SPACING            =$300A;
+  HMERR_DDF_HINSTANCE               =$300B;
+  HMERR_DDF_EXCEED_MAX_LENGTH       =$300C;
+  HMERR_DDF_EXCEED_MAX_INC          =$300D;
+  HMERR_DDF_INVALID_DDF             =$300E;
+  HMERR_DDF_FORMAT_TYPE             =$300F;
+  HMERR_DDF_INVALID_PARM            =$3010;
+  HMERR_DDF_INVALID_FONT            =$3011;
+  HMERR_DDF_SEVERE                  =$3012;
+
+//************************************************************************/
+//* Window Help API declarations.                                        */
+//************************************************************************/
+                                     
+function WinDestroyHelpInstance(hwndHelpInstance: HWND): Longbool; cdecl;
+function WinCreateHelpInstance(ahab: HAB; var phinitHMInitStructure: HELPINIT): HWND; cdecl;
+function WinAssociateHelpInstance(hwndHelpInstance, hwndApp: HWND): Longbool; cdecl;
+function WinQueryHelpInstance(hwndApp: HWND): HWND; cdecl;
+function WinLoadHelpTable(hwndHelpInstance: HWND; idHelpTable: cardinal; Module: cardinal): Longbool; cdecl;
+function WinCreateHelpTable(hwndHelpInstance: HWND; var phtHelpTable: HELPTABLE): Longbool; cdecl;
+function DdfInitialize(hwndHelpInstance: HWND; cbBuffer, ulIncrement: cardinal): HDDF; cdecl;
+function DdfPara(ahddf: HDDF):Longbool; cdecl;
+function DdfSetFormat(ahddf: HDDF; fFormatType: cardinal): Longbool; cdecl;
+function DdfSetTextAlign(ahddf: HDDF; fAlign: cardinal): Longbool; cdecl;
+function DdfSetColor(ahddf: HDDF; fBackColor, fForColor: Longint): Longbool; cdecl;
+function DdfInform(ahddf: HDDF; var pszText: PChar; resInformNumber: cardinal): Longbool; cdecl;
+function DdfSetFontStyle(ahddf: HDDF; fFontStyle: cardinal): Longbool; cdecl;
+function DdfHyperText(ahddf: HDDF; var pszText, pszReference: PChar; fReferenceType: cardinal): Longbool; cdecl;
+function DdfBeginList(ahddf: HDDF; ulWidthDT, fBreakType, fSpacing: cardinal): Longbool; cdecl;
+function DdfListItem(ahddf: HDDF; var pszTerm, pszDescription: PChar): Longbool; cdecl;
+function DdfEndList(ahddf: HDDF): Longbool; cdecl;
+function DdfMetafile(ahddf: HDDF; ahmf: cardinal; var prclRect: RECTL): Longbool; cdecl;
+function DdfText(ahddf: HDDF; var pszText: PChar): Longbool; cdecl;
+function DdfSetFont(ahddf: HDDF; var pszFaceName: PChar; ulWidth, ulHeight: cardinal): Longbool; cdecl;
+function DdfBitmap(ahddf: HDDF; hbm: HBITMAP; fAlign: cardinal): Longbool; cdecl;
+
+implementation
+
+const
+  HELPMGRDLL='HELPMGR';
+  
+function WinDestroyHelpInstance(hwndHelpInstance: HWND): Longbool; cdecl;
+    external HELPMGRDLL index 52;
+function WinCreateHelpInstance(ahab: HAB; var phinitHMInitStructure: HELPINIT): HWND; cdecl;
+    external HELPMGRDLL index 51;
+function WinAssociateHelpInstance(hwndHelpInstance, hwndApp: HWND): Longbool; cdecl;
+    external HELPMGRDLL index 54;
+function WinQueryHelpInstance(hwndApp: HWND): HWND; cdecl;
+    external HELPMGRDLL index 53;
+function WinLoadHelpTable(hwndHelpInstance: HWND; idHelpTable: cardinal; Module: cardinal): Longbool; cdecl;
+    external HELPMGRDLL index 55;
+function WinCreateHelpTable(hwndHelpInstance: HWND; var phtHelpTable: HELPTABLE): Longbool; cdecl;
+    external HELPMGRDLL index 56;
+function DdfInitialize(hwndHelpInstance: HWND; cbBuffer, ulIncrement: cardinal): HDDF; cdecl;
+    external HELPMGRDLL index 74;
+function DdfPara (ahddf: HDDF): Longbool; cdecl;
+    external HELPMGRDLL index 75;
+function DdfSetFormat(ahddf: HDDF; fFormatType: cardinal): Longbool; cdecl;
+    external HELPMGRDLL index 76;
+function DdfSetTextAlign (ahddf: HDDF; fAlign: cardinal): Longbool; cdecl;
+    external HELPMGRDLL index 77;
+function DdfSetColor(ahddf: HDDF; fBackColor, fForColor: Longint): Longbool; cdecl;
+    external HELPMGRDLL index 78;
+function DdfInform(ahddf: HDDF; var pszText: PChar; resInformNumber: cardinal): Longbool; cdecl;
+    external HELPMGRDLL index 79;
+function DdfSetFontStyle(ahddf: HDDF; fFontStyle: cardinal): Longbool; cdecl;
+    external HELPMGRDLL index 80;
+function DdfHyperText(ahddf: HDDF; var pszText, pszReference: PChar; fReferenceType: cardinal): Longbool; cdecl;
+    external HELPMGRDLL index 81;
+function DdfBeginList(ahddf: HDDF; ulWidthDT, fBreakType, fSpacing: cardinal): Longbool; cdecl;
+    external HELPMGRDLL index 82;
+function DdfListItem(ahddf: HDDF; var pszTerm, pszDescription: PChar): Longbool; cdecl;
+    external HELPMGRDLL index 83;
+function DdfEndList(ahddf: HDDF): Longbool; cdecl;
+    external HELPMGRDLL index 84;
+function DdfMetafile(ahddf: HDDF; ahmf: cardinal; var prclRect: RECTL): Longbool; cdecl;
+    external HELPMGRDLL index 86;
+function DdfText(ahddf: HDDF; var pszText: PChar): Longbool; cdecl;
+    external HELPMGRDLL index 85;
+function DdfSetFont(ahddf: HDDF; var pszFaceName: PChar; ulWidth, ulHeight: cardinal): Longbool; cdecl;
+    external HELPMGRDLL index 87;
+function DdfBitmap(ahddf: HDDF; hbm: HBITMAP; fAlign: cardinal): Longbool; cdecl;
+    external HELPMGRDLL index 88;
+
+end.