cde/programs/dtappbuilder/src/libABobj/trav.h

   1 /*
   2  * CDE - Common Desktop Environment
   3  *
   4  * Copyright (c) 1993-2012, The Open Group. All rights reserved.
   5  *
   6  * These libraries and programs are free software; you can
   7  * redistribute them and/or modify them under the terms of the GNU
   8  * Lesser General Public License as published by the Free Software
   9  * Foundation; either version 2 of the License, or (at your option)
  10  * any later version.
  11  *
  12  * These libraries and programs are distributed in the hope that
  13  * they will be useful, but WITHOUT ANY WARRANTY; without even the
  14  * implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE. See the GNU Lesser General Public License for more
  16  * details.
  17  *
  18  * You should have received a copy of the GNU Lesser General Public
  19  * License along with these librararies and programs; if not, write
  20  * to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
  21  * Floor, Boston, MA 02110-1301 USA
  22  */
  23
  24 /*
  25  *      $XConsortium: trav.h /main/3 1995/11/06 18:41:46 rswiston $
  26  *
  27  * @(#)trav.h   3.28 27 Apr 1994        cde_app_builder/src/libABobj
  28  *
  29  *      RESTRICTED CONFIDENTIAL INFORMATION:
  30  *
  31  *      The information in this document is subject to special
  32  *      restrictions in a confidential disclosure agreement between
  33  *      HP, IBM, Sun, USL, SCO and Univel.  Do not distribute this
  34  *      document outside HP, IBM, Sun, USL, SCO, or Univel without
  35  *      Sun's specific written approval.  This document and all copies
  36  *      and derivative works thereof must be returned or destroyed at
  37  *      Sun's request.
  38  *
  39  *      Copyright 1993 Sun Microsystems, Inc.  All rights reserved.
  40  *
  41  */
  42
  43 /*
  44  * Traversal.h - Handles object tree traversal.
  45  *
  46  * The AB_TRAVERSAL data type allows the client to easily visit objects
  47  * in a tree of ABObjs.  A great deal of flexibility is provided, with the
  48  * ability to select the types of objects to visit, the order they will be
  49  * visited in, and the ability to modify the tree while the traversal is
  50  * being performed.
  51  *
  52  * To traverse a tree, call trav_open with the root object of the tree to be
  53  * searched, along with a traversal specifier, which is a set of one or more
  54  * AB_TRAV_ constants.  The specifier defines exactly what types of objects
  55  * you want returned, and in what order you want them returned.  Note that
  56  * trav_open does not return an object - trav_next returns the first and all
  57  * successive objects.  Calling trav_next until it returns NULL will get
  58  * all of the objects selected by the traversal.  WHEN THE TRAVERSAL IS NO
  59  * LONGER NEEDED, YOU MUST USE trav_close() TO INVALIDATE IT.
  60  *
  61  * A traversal specifier is a bitwise-ored value, consisting of a traversal
  62  * type and zero or more modifiers.  Without a modifier, the default order
  63  * of visitation is undefined, although each selected object will be returned
  64  * exactly once. Note that once a traversal is opened, the traversal specifier
  65  * cannot be changed.
  66  *
  67  * Traversal type
  68  * --------------
  69  * The traveral type defines the object selection (what types/classes of
  70  * objects are visited).  Only one traversal type can be specified, and
  71  * if no traversal type is specified, AB_TRAV_ALL is assumed.
  72  * Commonly used types are AB_TRAV_UI, AB_TRAV_SALIENT and AB_TRAV_SALIENT_UI
  73  *
  74  * Traversal modifier
  75  * ------------------
  76  * Modifiers may be used in any combination to modify the behavior of a
  77  * traversal.
  78  *
  79  *  AB_TRAV_MOD_PARENTS_FIRST   returns the parents (ancestors) of an object
  80  *                              before returning the object itself.  This does
  81  *                              not change the objects returned, only their
  82  *                              ordering.
  83  *
  84  *  AB_TRAV_MOD_SAFE            allows the tree to be modified while the
  85  *                              traversal is being performed.  Note
  86  *                              that if an object is destroyed, an invalid
  87  *                              reference to it will be returned by the
  88  *                              traversal. However, since each object is
  89  *                              returned only once, destroying an object
  90  *                              after it is returned should avoid most
  91  *                              problems.
  92  *
  93  * Note that all of the calls to the trav_ functions require a first
  94  * parameter of type (AB_TRAVERSAL *).  This must be a pointer to a
  95  * previously-allocated structure (e.g., the address of a local variable
  96  * of type AB_TRAVERSAL).
  97  *
  98  *
  99  * E.g.:
 100  *
 101  * int
 102  * show_objects(ABObj root)
 103  * {
 104  *     AB_TRAVERSAL trav;
 105  *     for (trav_open(&trav, root, AB_TRAV_SALIENT_UI | AB_TRAV_MOD_SAFE);
 106  *          (obj= trav_next(&trav)) != NULL; )
 107  *     {
 108  *         -- operate on obj
 109  *     }
 110  *     trav_close(&trav);  -- gotta close!
 111  *     return 0;
 112  * }
 113  *
 114  *
 115  * Other examples of opening a traversal:
 116  *
 117  *      trav_open(&trav, rootObj, AB_TRAV_WINDOWS | AB_TRAV_MOD_SAFE);
 118  *      trav_open(&trav, rootObj, AB_TRAV_UI | AB_TRAV_MOD_SAFE);
 119  *      trav_open(&trav, rootObj, AB_TRAV_MOD_PARENT_FIRST);
 120  *
 121  */
 122 #ifndef _ABOBJ_TRAVERSAL_H_
 123 #define _ABOBJ_TRAVERSAL_H_
 124
 125 #include <ab_private/obj.h>
 126
 127 /*
 128  * Traversal types (see comment at top of this file)
 129  */
 130 #define AB_TRAV_UNDEF                   (0U)   /* invalid traversal type */
 131 #define AB_TRAV_ACTIONS                 (1U)   /* actions only */
 132 #define AB_TRAV_ACTIONS_FOR_OBJ         (2U)  /* actions for root object only */
 133 #define AB_TRAV_ALL                     (3U)
 134 #define AB_TRAV_CHILDREN                (4U)   /* ONLY IMMEDIATE CHILDREN! */
 135 #define AB_TRAV_FILES                   (5U)
 136 #define AB_TRAV_GROUPS                  (6U)
 137 #define AB_TRAV_ITEMS                   (7U)   /* all items in tree */
 138 #define AB_TRAV_ITEMS_FOR_OBJ           (8U)   /* items for object only */
 139 #define AB_TRAV_MENUS                   (9U)   /* all types of menus */
 140 #define AB_TRAV_MODULES                 (10U)
 141 #define AB_TRAV_PARENTS                 (11U)
 142 #define AB_TRAV_SALIENT                 (12U)   /*user-manipulatable objects*/
 143 #define AB_TRAV_SALIENT_UI              (13U)   /* salient && ui */
 144 #define AB_TRAV_SALIENT_CHILDREN        (14U)  /*user-manipulatable children*/
 145 #define AB_TRAV_SALIENT_UI_CHILDREN     (15U)
 146 #define AB_TRAV_SIBLINGS                (16U)
 147 #define AB_TRAV_UI                      (17U)   /* all ui objs (no actions) */
 148 #define AB_TRAV_WINDOWS                 (18U)   /* all windows */
 149 #define AB_TRAV_COMP_SUBOBJS            (19U)   /* subobjs of this comp. obj */
 150
 151 /*
 152  * Traversal modifiers (see comment at top of this file)
 153  */
 154 #define AB_TRAV_MOD_PARENTS_FIRST       (0x0100U)
 155 #define AB_TRAV_MOD_SAFE                (0x0200U)
 156
 157
 158 /*
 159  * Traversal data structure
 160  */
 161 typedef struct
 162 {
 163         unsigned        travType;
 164         ABObj           rootObj;
 165         ABObj           curObj;
 166         ABObj           *objArray;
 167         int             objArraySize;
 168         int             objArrayIndex;
 169         BOOL            done;
 170         ABObjTestFunc   testFunc;
 171 } AB_TRAVERSAL;
 172 typedef AB_TRAVERSAL *ABTraversal;
 173
 174 /*
 175  * callback for trav_perform.  return of negative value aborts traversal.
 176  */
 177 typedef int (*AB_TRAVERSAL_CB)(ABObj obj);
 178 typedef AB_TRAVERSAL_CB ABTraversalCB;
 179
 180 int             trav_open(ABTraversal trav, ABObj root, unsigned trav_type);
 181 int             trav_open_cond(
 182                         ABTraversal     trav,
 183                         ABObj           root,
 184                         unsigned        trav_type,
 185                         ABObjTestFunc   cond_test_func
 186                 );
 187 ABObj           trav_obj(ABTraversal trav);
 188 ABObj           trav_next(ABTraversal trav);
 189 ABObj           trav_goto(ABTraversal trav, int which);
 190 int             trav_close(ABTraversal trav);
 191 BOOL            trav_is_open(ABTraversal trav);
 192 int             trav_reset(ABTraversal trav);
 193
 194 /* Returns the # of objects that will be returned by the traversal.
 195  */
 196 int             trav_count(ABObj root, int trav_type);
 197 int             trav_count_cond(ABObj root, int trav_type, ABObjTestFunc);
 198
 199 /*
 200  * Performs the traversal, calling clientfunc on each object.  A negative
 201  * return from clientfunc aborts the traversal.
 202  */
 203 int             trav_perform(ABObj root, int trav_type,
 204                                 AB_TRAVERSAL_CB clientfunc);
 205
 206 /*************************************************************************
 207 **                                                                      **
 208 **              Inline implementations                                  **
 209 **                                                                      **
 210 **************************************************************************/
 211
 212 #define trav_is_open(trav)      ((trav)->rootObj != NULL)
 213 #define trav_obj(trav)          ((trav)->curObj)
 214
 215 #endif /* _ABOBJ_TRAVERSAL_H_ */
 216