helpdialog.h

/* helpdialog.h */
/* $Id: helpdialog.h,v 1.4 2006/10/09 11:16:24 shurik Exp $ */
#ifndef __helpdialog_h
#define __helpdialog_h

/***********************************************************************
 *
 *                       Context help subsystem
 *
 ***********************************************************************/

/***********************************************************************
 *                         Help dialog window
 ***********************************************************************/

#include <X11/Intrinsic.h>
#include <Xm/Text.h>

#include <mix/helpdoc.h>


/* Recommended width for help text and titles */
#define ZmHW_CONTENTS_WIDTH     60


#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */


/* Structure for the help dialog window history item */
typedef struct ZmHelpHistItemTag
{
  struct ZmHelpHistItemTag  *pNext, *pPrev; /* bidirection list */
  const char            *szSection; /* section's label */

}   ZmHelpHistItem;

/* Structure for the help dialog window state */
typedef struct
{
  short     nTextRows, nTextCols;   /* help text window size */
  XmTextPosition    nTextPos;   /* position in text */
  int       nRefLines;  /* visible lines in list of refs */
  int       nRefPos;    /* position in list of refs */
  Position  xPos, yPos; /* common window position */

}   ZmHelpWinState;

/* Structure for the help dialog window */
typedef struct
{
  /* initial command line arguments */
  char      **argv;
  int       argc;

  /* context help dialog */
  Widget    wShell;     /* window shell */
  Widget    wForm, wToolbar, wPaned;    /* composites */
  Widget    wDocTitleLabel; /* title label for the document */
  Widget    wSectionTitleLabel;/* title label for the section */
  Widget    wCloseHelp, wNextSection, wPrevSection, wListOfSections;
  Widget    wHelpText;  /* help text */
  Widget    wHelpRefs;  /* list of references */

  ZmHelpWinState    state;  /* state of the window */

  /* table of contents dialog */
  Widget    wTOCShell;  /* window shell */
  Widget    wTOCForm;   /* container */
  Widget    wTOCSelBox; /* selection box */

  /* history */
  ZmHelpHistItem    *last;  /* last item of history (list head) */
  ZmHelpHistItem    *cur;   /* current item of history */

  ChDocument    *doc;       /* context help document structure */
  ChReference   *toc;       /* table of contents */
  Logic     bFirst;     /* first call */

  /* language-dependent dynamic resources */
  XmFontList    flTextFont; /* text, refs, common title */
  TextEncoding  eTextFontEnc;

  XmFontList    flTitleFont;    /* section title */
  TextEncoding  eTitleFontEnc;

}   ZmHelpWinInternals;


/* Initialize server code (before GUI start). */
ErrCode ZmInitHelpWindow (const char* szMainHelpDoc, Widget w);


/* Add another document to help repository. */
void    ZmHW_AddHelpDoc (ZmHelpWinInternals* pHWI, const char* szDocName);

/* Create help window. */
void    ZmHW_CreateHelpDialog (ZmHelpWinInternals* pHWI);

/* Assign pixmaps to push buttons of help dialog. */
void    ZmHW_AssignPixmaps (ZmHelpWinInternals* pHWI);

/* Create table of contents dialog */
void    ZmHW_CreateTOCDialog (Widget wParent, ZmHelpWinInternals* pHWI);

/* Register callbacks */
void    ZmHW_RegisterCallbacksHelpWin (ZmHelpWinInternals* pHWI);

/* Store state of the window in special state variable */
void    ZmHW_StoreHelpWinState (ZmHelpWinInternals* pHWI);

/* Restore state of the window from special state variable */
void    ZmHW_RestoreHelpWinState (ZmHelpWinInternals* pHWI);

/* Setup state of the window */
void    ZmHW_SetupHelpWinState (ZmHelpWinInternals* pHWI);

/* Place help window */
void    ZmHW_PlaceHelpWin (Widget wParent, ZmHelpWinInternals* pHWI);

/* Set localized fonts to some GUI items. */
void    ZmHW_ForceLocalizedFonts (ZmHelpWinInternals* pHWI);

/* Display given text translated from some encoding to another. */
void    ZmHW_SetLocalizedString (Widget wTarget, TextEncoding eTargetEnc,
                 TextEncoding eSourceEnc, const char* szString);

/* Display help section labeled by szSection in given help window
   context. */
void    ZmHW_HelpShow (ZmHelpWinInternals* pHWI, const char* szSection);

/* Display current section. */
void    ZmHW_DisplayCurrentSection (ZmHelpWinInternals* pHWI);

/* Find index of reference in list or -1. */
int     ZmHW_FindIndexOfReference (ChReference* pHead,
                       ChReference* pRef);

/* Find reference by index in list or NULL. */
ChReference*    ZmHW_FindReferenceByIndex (ChReference* pHead,
                       int iRef);

/* Fill table of contents */
void    ZmHW_FillTOCDialog (ZmHelpWinInternals* pHWI);

/* Erase all items from table of contents */
void    ZmHW_CleanTOCDialog (ZmHelpWinInternals* pHWI);


/***********************************************************************
 * Error notification
 ***********************************************************************/

/* Display error message about unknown section. */
void    ZmHW_ErrorSectionIsNotFound (ZmHelpWinInternals* pHWI,
                     const char* szSection);


/***********************************************************************
 * History
 ***********************************************************************/

/* Add section to the end of history list. */
ZmHelpHistItem* ZmHW_AddSectionToHistory (ZmHelpWinInternals* pHWI,
                      const char* szSection);

/* History walking buttons' sensitivity. */
void    ZmHW_HistoryButtonsSensitivity (ZmHelpWinInternals* pHWI);

/* Debug tool for history. */
void    ZmHW_PrintHistory (ZmHelpWinInternals* pHWI);


/***********************************************************************
 * Callbacks
 ***********************************************************************/

#define DeclareCallback(f)  void    f(Widget, XtPointer, XtPointer)

/* Handle closure of the help window */
DeclareCallback(ZmHW_CloseHelpWinCB);

/* Handle prev history item button of the help window */
DeclareCallback(ZmHW_PrevHelpItemCB);

/* Handle next history item button of the help window */
DeclareCallback(ZmHW_NextHelpItemCB);

/* Handle list of help contents button of the help window */
DeclareCallback(ZmHW_HelpContentsCB);

/* Handle double-click on reference */
DeclareCallback(ZmHW_SelectRefCB);

/* Handle OK (selected) event in TOC dialog window */
DeclareCallback(ZmHW_TOCOkCB);

/* Handle Cancel/Close event in TOC dialog window */
DeclareCallback(ZmHW_TOCCancelCB);

#undef DeclareCallback


#ifdef __HelpWinVars
#define EXTERN
#else
#define EXTERN  extern
#endif /* __HelpWinVars */

/* General application context help window */
EXTERN ZmHelpWinInternals   *pAppHelpWin;


EXTERN char *szCwd,*szHelpDir;

#undef EXTERN


#ifdef __cplusplus
};
#endif /* __cplusplus */

#endif /* helpdialog.h */