217 lines
7.4 KiB
C
217 lines
7.4 KiB
C
/*
|
|
* CDE - Common Desktop Environment
|
|
*
|
|
* Copyright (c) 1993-2012, The Open Group. All rights reserved.
|
|
*
|
|
* These libraries and programs are free software; you can
|
|
* redistribute them and/or modify them under the terms of the GNU
|
|
* Lesser General Public License as published by the Free Software
|
|
* Foundation; either version 2 of the License, or (at your option)
|
|
* any later version.
|
|
*
|
|
* These libraries and programs are distributed in the hope that
|
|
* they will be useful, but WITHOUT ANY WARRANTY; without even the
|
|
* implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
|
|
* PURPOSE. See the GNU Lesser General Public License for more
|
|
* details.
|
|
*
|
|
* You should have received a copy of the GNU Lesser General Public
|
|
* License along with these libraries and programs; if not, write
|
|
* to the Free Software Foundation, Inc., 51 Franklin Street, Fifth
|
|
* Floor, Boston, MA 02110-1301 USA
|
|
*/
|
|
|
|
/*
|
|
* $XConsortium: trav.h /main/3 1995/11/06 18:41:46 rswiston $
|
|
*
|
|
* @(#)trav.h 3.28 27 Apr 1994 cde_app_builder/src/libABobj
|
|
*
|
|
* RESTRICTED CONFIDENTIAL INFORMATION:
|
|
*
|
|
* The information in this document is subject to special
|
|
* restrictions in a confidential disclosure agreement between
|
|
* HP, IBM, Sun, USL, SCO and Univel. Do not distribute this
|
|
* document outside HP, IBM, Sun, USL, SCO, or Univel without
|
|
* Sun's specific written approval. This document and all copies
|
|
* and derivative works thereof must be returned or destroyed at
|
|
* Sun's request.
|
|
*
|
|
* Copyright 1993 Sun Microsystems, Inc. All rights reserved.
|
|
*
|
|
*/
|
|
|
|
/*
|
|
* Traversal.h - Handles object tree traversal.
|
|
*
|
|
* The AB_TRAVERSAL data type allows the client to easily visit objects
|
|
* in a tree of ABObjs. A great deal of flexibility is provided, with the
|
|
* ability to select the types of objects to visit, the order they will be
|
|
* visited in, and the ability to modify the tree while the traversal is
|
|
* being performed.
|
|
*
|
|
* To traverse a tree, call trav_open with the root object of the tree to be
|
|
* searched, along with a traversal specifier, which is a set of one or more
|
|
* AB_TRAV_ constants. The specifier defines exactly what types of objects
|
|
* you want returned, and in what order you want them returned. Note that
|
|
* trav_open does not return an object - trav_next returns the first and all
|
|
* successive objects. Calling trav_next until it returns NULL will get
|
|
* all of the objects selected by the traversal. WHEN THE TRAVERSAL IS NO
|
|
* LONGER NEEDED, YOU MUST USE trav_close() TO INVALIDATE IT.
|
|
*
|
|
* A traversal specifier is a bitwise-ored value, consisting of a traversal
|
|
* type and zero or more modifiers. Without a modifier, the default order
|
|
* of visitation is undefined, although each selected object will be returned
|
|
* exactly once. Note that once a traversal is opened, the traversal specifier
|
|
* cannot be changed.
|
|
*
|
|
* Traversal type
|
|
* --------------
|
|
* The traveral type defines the object selection (what types/classes of
|
|
* objects are visited). Only one traversal type can be specified, and
|
|
* if no traversal type is specified, AB_TRAV_ALL is assumed.
|
|
* Commonly used types are AB_TRAV_UI, AB_TRAV_SALIENT and AB_TRAV_SALIENT_UI
|
|
*
|
|
* Traversal modifier
|
|
* ------------------
|
|
* Modifiers may be used in any combination to modify the behavior of a
|
|
* traversal.
|
|
*
|
|
* AB_TRAV_MOD_PARENTS_FIRST returns the parents (ancestors) of an object
|
|
* before returning the object itself. This does
|
|
* not change the objects returned, only their
|
|
* ordering.
|
|
*
|
|
* AB_TRAV_MOD_SAFE allows the tree to be modified while the
|
|
* traversal is being performed. Note
|
|
* that if an object is destroyed, an invalid
|
|
* reference to it will be returned by the
|
|
* traversal. However, since each object is
|
|
* returned only once, destroying an object
|
|
* after it is returned should avoid most
|
|
* problems.
|
|
*
|
|
* Note that all of the calls to the trav_ functions require a first
|
|
* parameter of type (AB_TRAVERSAL *). This must be a pointer to a
|
|
* previously-allocated structure (e.g., the address of a local variable
|
|
* of type AB_TRAVERSAL).
|
|
*
|
|
*
|
|
* E.g.:
|
|
*
|
|
* int
|
|
* show_objects(ABObj root)
|
|
* {
|
|
* AB_TRAVERSAL trav;
|
|
* for (trav_open(&trav, root, AB_TRAV_SALIENT_UI | AB_TRAV_MOD_SAFE);
|
|
* (obj= trav_next(&trav)) != NULL; )
|
|
* {
|
|
* -- operate on obj
|
|
* }
|
|
* trav_close(&trav); -- gotta close!
|
|
* return 0;
|
|
* }
|
|
*
|
|
*
|
|
* Other examples of opening a traversal:
|
|
*
|
|
* trav_open(&trav, rootObj, AB_TRAV_WINDOWS | AB_TRAV_MOD_SAFE);
|
|
* trav_open(&trav, rootObj, AB_TRAV_UI | AB_TRAV_MOD_SAFE);
|
|
* trav_open(&trav, rootObj, AB_TRAV_MOD_PARENT_FIRST);
|
|
*
|
|
*/
|
|
#ifndef _ABOBJ_TRAVERSAL_H_
|
|
#define _ABOBJ_TRAVERSAL_H_
|
|
|
|
#include <ab_private/obj.h>
|
|
|
|
/*
|
|
* Traversal types (see comment at top of this file)
|
|
*/
|
|
#define AB_TRAV_UNDEF (0U) /* invalid traversal type */
|
|
#define AB_TRAV_ACTIONS (1U) /* actions only */
|
|
#define AB_TRAV_ACTIONS_FOR_OBJ (2U) /* actions for root object only */
|
|
#define AB_TRAV_ALL (3U)
|
|
#define AB_TRAV_CHILDREN (4U) /* ONLY IMMEDIATE CHILDREN! */
|
|
#define AB_TRAV_FILES (5U)
|
|
#define AB_TRAV_GROUPS (6U)
|
|
#define AB_TRAV_ITEMS (7U) /* all items in tree */
|
|
#define AB_TRAV_ITEMS_FOR_OBJ (8U) /* items for object only */
|
|
#define AB_TRAV_MENUS (9U) /* all types of menus */
|
|
#define AB_TRAV_MODULES (10U)
|
|
#define AB_TRAV_PARENTS (11U)
|
|
#define AB_TRAV_SALIENT (12U) /*user-manipulatable objects*/
|
|
#define AB_TRAV_SALIENT_UI (13U) /* salient && ui */
|
|
#define AB_TRAV_SALIENT_CHILDREN (14U) /*user-manipulatable children*/
|
|
#define AB_TRAV_SALIENT_UI_CHILDREN (15U)
|
|
#define AB_TRAV_SIBLINGS (16U)
|
|
#define AB_TRAV_UI (17U) /* all ui objs (no actions) */
|
|
#define AB_TRAV_WINDOWS (18U) /* all windows */
|
|
#define AB_TRAV_COMP_SUBOBJS (19U) /* subobjs of this comp. obj */
|
|
|
|
/*
|
|
* Traversal modifiers (see comment at top of this file)
|
|
*/
|
|
#define AB_TRAV_MOD_PARENTS_FIRST (0x0100U)
|
|
#define AB_TRAV_MOD_SAFE (0x0200U)
|
|
|
|
|
|
/*
|
|
* Traversal data structure
|
|
*/
|
|
typedef struct
|
|
{
|
|
unsigned travType;
|
|
ABObj rootObj;
|
|
ABObj curObj;
|
|
ABObj *objArray;
|
|
int objArraySize;
|
|
int objArrayIndex;
|
|
BOOL done;
|
|
ABObjTestFunc testFunc;
|
|
} AB_TRAVERSAL;
|
|
typedef AB_TRAVERSAL *ABTraversal;
|
|
|
|
/*
|
|
* callback for trav_perform. return of negative value aborts traversal.
|
|
*/
|
|
typedef int (*AB_TRAVERSAL_CB)(ABObj obj);
|
|
typedef AB_TRAVERSAL_CB ABTraversalCB;
|
|
|
|
int trav_open(ABTraversal trav, ABObj root, unsigned trav_type);
|
|
int trav_open_cond(
|
|
ABTraversal trav,
|
|
ABObj root,
|
|
unsigned trav_type,
|
|
ABObjTestFunc cond_test_func
|
|
);
|
|
ABObj trav_obj(ABTraversal trav);
|
|
ABObj trav_next(ABTraversal trav);
|
|
ABObj trav_goto(ABTraversal trav, int which);
|
|
int trav_close(ABTraversal trav);
|
|
BOOL trav_is_open(ABTraversal trav);
|
|
int trav_reset(ABTraversal trav);
|
|
|
|
/* Returns the # of objects that will be returned by the traversal.
|
|
*/
|
|
int trav_count(ABObj root, int trav_type);
|
|
int trav_count_cond(ABObj root, int trav_type, ABObjTestFunc);
|
|
|
|
/*
|
|
* Performs the traversal, calling clientfunc on each object. A negative
|
|
* return from clientfunc aborts the traversal.
|
|
*/
|
|
int trav_perform(ABObj root, int trav_type,
|
|
AB_TRAVERSAL_CB clientfunc);
|
|
|
|
/*************************************************************************
|
|
** **
|
|
** Inline implementations **
|
|
** **
|
|
**************************************************************************/
|
|
|
|
#define trav_is_open(trav) ((trav)->rootObj != NULL)
|
|
#define trav_obj(trav) ((trav)->curObj)
|
|
|
|
#endif /* _ABOBJ_TRAVERSAL_H_ */
|
|
|