Creating a Dialog Cache

Because authors can create hyperlinks that request a new window, your application must be able to create an arbitrary number of help windows. But, creating and destroying widgets as they are needed can cause your application to run slower. So, to optimize performance and make efficient use of resources, caching help dialogs is recommended.

A dialog cache is a list of the help dialogs that your application has already created. When the user dismisses a dialog, the widget stays in the cache instead of being destroyed.

The next time the user requests help that would otherwise require a new widget, your application can scan the cache list looking for a dialog that isn't currently being used.

To create a dialog cache

Declare a structure that you can use to create a linked list of dialogs. Typically, a help dialog cache structure has these attributes:
- Keeps track of the Widget ID for each help dialog.
- Maintains a flag that indicates which type of help dialog it is (quick help or general help).
- Maintains an "in use" flag.
When you create a help dialog, be sure to add it to your cache.
When the user closes a help dialog, return the dialog to your cache by clearing its "in use" flag, then unmanage it.

Example. The following type definition demonstrates a simple structure that you could use to build a dialog cache. Instances of this structure would be connected (via the next element) to form a linked list.

   typedef struct _HelpDialogCacheStruct {

        Widget   dialog;                         /* The dialog's handle. */

        Boolean  inUse;                          /* The `in use' flag. */

        Boolean  isQuickHelpDialog;              /* The dialog type flag. */

        struct   _HelpDialogCacheStruct  *next;  /* Next in the list. */

   }  HelpDialogCacheStruct;

To retrieve a dialog from your cache

Scan the cache looking for a dialog of the correct type whose "in use" flag is false. If there are no dialogs available in the cache, create a new one, add it to the cache (marked "in use") and use it.

Example. The following FetchHelpDialog() function scans a dialog cache for a help dialog of the specified type and returns a Widget ID. If an unused dialog is not found, one is created, added to the cache and returned. (If you are viewing this example online, you can copy and paste this example directly into your source code to save the trouble of typing it.)

   Widget

   FetchHelpDialog(Boolean  lookingForQuickHelpDialog)

     {

        /* Declare a local pointer for walking the cache. */

        HelpDialogCacheStruct *pCacheStruct;



        /* Declare another, in case we need to add a new item to the cache. */

        HelpDialogCacheStruct *pNewCacheStruct;



        /* Set the local pointer to the first item in the cache list. */

        pCacheStruct = pFirstHelpDialogCacheStruct;



        /* Scan the cache for an unused help dialog. */

        while (pCacheStruct != (_HelpDialogCacheStruct)NULL)

          {

             /* Is this dialog available? */

             if (  (pCacheStruct->inUse == False)

                     /* And, is it the correct type? */

                 &&  (  (   lookingForQuickHelpDialog

                         && pCacheStruct->isQuickHelpDialog)

                     || (   !lookingForQuickHelpDialog

                         && !pCacheStruct->isQuickHelpDialog)))

               {

                  /* Yes!  This is a match. */

                  pCacheStruct->inUse = True;

                  return ((Widget)pCacheStruct->dialog);

               }

             else

               {

                  /* Nope.  Go on to the next item. */

                  pCacheStruct = pCacheStruct->next;

               }

          }

   

        /* Searching the cache was unsuccessful.*/

   

        /* Create a new item in the cache. */

        pNewCacheStruct = (HelpDialogCacheStruct *)

             XtMalloc((sizeof(HelpDialogCacheStruct)));

   

        /* Fill in the new structure. */

        pNewCacheStruct->inUse = True;

        pNewCacheStruct->isQuickHelpDialog = 

             lookingForQuickHelpDialog;

        pNewCacheStruct->next = 

             pFirstHelpDialogCacheStruct->next;

        pFirstHelpDialogCacheStruct = pNewCacheStruct;

   

        /* Create the new help dialog widget. */

        ac = 0;

        XtSetArg (al[ac], XmNtitle, "My Application - Help"); ac++;

        if (lookingForQuickHelpDialog)

          {

             pNewCacheStruct->dialog = XvhCreateQuickHelpDialog 

                  (topLevel, "quickHelpDialog", al, ac);

          }

        else

          {

             pNewCacheStruct->dialog = XvhCreateHelpDialog 

                  (topLevel, "helpDialog", al, ac);

          }

   

        /* Done.  Return the new dialog. */

        return ((Widget)pNewCacheStruct->dialog);

     }

The example above assumes the following:

That the pointer to the head of the cache (pFirstHelpDialogCacheStruct) is initialized to NULL during application start up.
That the calling routine tests the return value to determine if a valid widget ID is returned.
That the parent for all help dialogs is a widget named topLevel.
That the variables al and ac (used in Xt argument lists) are declared external to this function.
The help volume name is "MyApplication."

To return a dialog to your cache

Unmanage the dialog and clear the dialog's "in use" flag.

Example. The following function is called when a help dialog is closed (via the close callback):

   Boolean

   HelpCloseCB (

        Widget     closedDialog,

        XtPointer  clientData,

        XtPointer  callData )

     {

       /* Declare a local pointer for walking the cache. */

       HelpDialogCacheStruct *pCacheStruct;

   

       /* Search the cache list for dialog. */

       pCacheStruct = pFirstHelpDialogCacheStruct;

   

       while (pCacheStruct != (HelpDialogCacheStruct *)NULL)

         {

           if (pCacheStruct->dialog == closedDialog)

             break;

           pCacheStruct = pCacheStruct->next;

         }



       /* Unmanage the dialog. */

       XtUnmanageChild(closedDialog);

   

       /* If the dialog wasn't found, the cache is corrupt.  Return failure. */

       if (pCacheStruct == (HelpDialogCacheStruct *)NULL)

         return (False);

   

       /* Mark the dialog unused, then return success. */

       pCacheStruct->inUse = False;

       return (True);

     }

Creating a Dialog Cache

Technical documentation

» Table of Contents

» Glossary

» Index

To create a dialog cache

To retrieve a dialog from your cache

To return a dialog to your cache