doc/ttk_vsapi.n


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

'\"
'\" Copyright (c) 2008 Pat Thoyts
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\" 
.so man.macros
.TH ttk_vsapi n 8.5 Tk "Tk Themed Widget"
.BS
.SH NAME
ttk_vsapi \- Define a Microsoft Visual Styles element
.SH SYNOPSIS
\fBttk::style element create \fIname\fR \fBvsapi\fR \fIclassName\fR \fIpartId\fR ?\fIstateMap\fR? ?\fIoptions\fR?
.BE
.SH DESCRIPTION
.PP
The \fBvsapi\fR element factory creates a new element
in the current theme whose visual appearance is drawn using the
Microsoft Visual Styles API which is responsible for the themed styles
on Windows XP and Vista. This factory permits any of the Visual
Styles parts to be declared as Ttk elements that can then be
included in a style layout to modify the appearance of Ttk widgets.
.PP
\fIclassName\fR and \fIpartId\fR are required parameters and specify
the Visual Styles class and part as given in the Microsoft
documentation. The \fIstateMap\fR may be provided to map Ttk states to
Visual Styles API states (see \fBSTATE MAP\fR).
.SH "OPTIONS"
.PP
Valid \fIoptions\fR are:
.TP
\fB\-padding \fIpadding\fR
.
Specify the element's interior padding.
\fIpadding\fR is a list of up to four integers specifying
the left, top, right and bottom padding quantities respectively.
This option may not be mixed with any other options.
.TP
\fB\-margins \fIpadding\fR
.
Specifies the elements exterior padding.
\fIpadding\fR is a list of up to four integers specifying
the left, top, right and bottom padding quantities respectively.
This option may not be mixed with any other options.
.TP
\fB\-width \fIwidth\fR
.
Specifies the height for the element. If this option is set then
the Visual Styles API will not be queried for the recommended
size or the part. If this option is set then \fB\-height\fR should
also be set. The \fB\-width\fR and \fB\-height\fR options cannot
be mixed with the \fB\-padding\fR or \fB\-margins\fR options.
.TP
\fB\-height \fIheight\fR
.
Specifies the height of the element. See the comments for \fB\-width\fR.
.SH "STATE MAP"
.PP
The \fIstateMap\fR parameter is a list of ttk states and the
corresponding Visual Styles API state value.
This permits the element appearance to respond to changes in the
widget state such as becoming active or being pressed. The list should
be as described for the \fBttk::style map\fR command but note that the
last pair in the list should be the default state and is typically and
empty list and 1. Unfortunately all the Visual Styles parts have
different state values and these must be looked up either in the
Microsoft documentation or more likely in the header files. The
original header to use was \fItmschema.h\fR, but in more recent
versions of the Windows Development Kit this is \fIvssym32.h\fR.
.PP
If no \fIstateMap\fR parameter is given there is an implicit default
map of {{} 1}
.SH "EXAMPLE"
.PP
Create a correctly themed close button by changing the layout of 
a \fBttk::button\fR(n). This uses the WINDOW part WP_SMALLCLOSEBUTTON
and as documented the states CBS_DISABLED, CBS_HOT, CBS_NORMAL and
CBS_PUSHED are mapped from ttk states.
.CS
ttk::style element create smallclose \fBvsapi\fR WINDOW 19 \\
    {disabled 4 pressed 3 active 2 {} 1}
ttk::style layout CloseButton {CloseButton.smallclose -sticky news}
pack [ttk::button .close -style CloseButton]
.CE
.PP
Change the appearance of a \fBttk::checkbutton\fR(n) to use the
Explorer pin part EBP_HEADERPIN.
.CS
ttk::style element create pin \fBvsapi\fR EXPLORERBAR 3 {
    {pressed !selected} 3
    {active !selected} 2
    {pressed selected} 6
    {active selected} 5
    {selected} 4
    {} 1
}
ttk::style layout Explorer.Pin {Explorer.Pin.pin -sticky news}
pack [ttk::checkbutton .pin -style Explorer.Pin]
.CE
.SH "SEE ALSO"
ttk::intro(n), ttk::widget(n), ttk::style(n), ttk_image(n)
.SH "KEYWORDS"
style, theme, appearance, windows
'\" Local Variables:
'\" mode: nroff
'\" End:
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.                                               *
 * Copyright by the Board of Trustees of the University of Illinois.         *
 * All rights reserved.                                                      *
 *                                                                           *
 * This file is part of HDF5.  The full HDF5 copyright notice, including     *
 * terms governing use, modification, and redistribution, is contained in    *
 * the files COPYING and Copyright.html.  COPYING can be found at the root   *
 * of the source code distribution tree; Copyright.html can be found at the  *
 * root level of an installed copy of the electronic HDF5 document set and   *
 * is linked from the top-level documents page.  It can also be found at     *
 * http://hdfgroup.org/HDF5/doc/Copyright.html.  If you do not have          *
 * access to either file, you may request a copy from help@hdfgroup.org.     *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*
 * FILE:	H5I.c - Internal storage routines for handling "IDs"
 *
 * REMARKS:	ID's which allow objects (void *'s currently) to be bundled
 *		into "types" for more general storage.
 *
 * DESIGN:	The types are stored in an array of pointers to store each
 *		type in an element. Each "type" node contains a link to a
 *		hash table to manage the IDs in each type.  Allowed types are
 *		values within the range 1 to MAX_NUM_TYPES and are given out
 *		at run-time.  Types used by the library are stored in global
 *		variables defined in H5Ipublic.h.
 *
 * AUTHOR:	Quincey Koziol
 *
 * MODIFICATIONS:
 *	1/3/96	- Starting writing specs & coding prototype
 *	1/7/96	- Finished coding prototype
 *	6/10/97 - Moved into HDF5 library
 *	5/18/04 - Expanded to allow registration of new types at run-time
 */

#define H5I_PACKAGE		/*suppress error about including H5Ipkg	  */

/* Interface initialization */
#define H5_INTERFACE_INIT_FUNC	H5I_init_interface


#include "H5private.h"		/* Generic Functions			*/
#include "H5ACprivate.h"        /* Metadata cache                       */
#include "H5Eprivate.h"		/* Error handling		  	*/
#include "H5FLprivate.h"	/* Free Lists                           */
#include "H5Ipkg.h"		/* IDs			  		*/
#include "H5MMprivate.h"	/* Memory management			*/
#include "H5Oprivate.h"		/* Object headers		  	*/

/* Define this to compile in support for dumping ID information */
/* #define H5I_DEBUG_OUTPUT */
#ifndef H5I_DEBUG_OUTPUT
#include "H5Gprivate.h"		/* Groups				*/
#else /* H5I_DEBUG_OUTPUT */
#define H5G_PACKAGE /*suppress error message about including H5Gpkg.h */
#include "H5Gpkg.h"		/* Groups		  		*/
#include "H5Dprivate.h"		/* Datasets				*/
#include "H5Tprivate.h"		/* Datatypes				*/
#endif /* H5I_DEBUG_OUTPUT */

/* Local Macros */

/* Define the maximum number of returned ID structures to keep around
   for re-use. */
#define MAX_FREE_ID_STRUCTS 1000

/*
 * Define the following macro for fast hash calculations (but limited
 * hash sizes)
 */
#define HASH_SIZE_POWER_2

#ifdef HASH_SIZE_POWER_2
/*
 * Map an ID to a hash location (assumes s is a power of 2 and smaller
 * than the ID_MASK constant).
 */
#  define H5I_LOC(a,s)		((hid_t)((size_t)(a)&((s)-1)))
#else
/*
 * Map an ID to a hash location.
 */
#  define H5I_LOC(a,s)	(((hid_t)(a)&ID_MASK)%(s))
#endif

/* Combine a Type number and an atom index into an atom */
#define H5I_MAKE(g,i)	((((hid_t)(g)&TYPE_MASK)<<ID_BITS)|	  \
			     ((hid_t)(i)&ID_MASK))

/* Local typedefs */

/* Atom information structure used */
typedef struct H5I_id_info_t {
    hid_t	id;		/* ID for this info			    */
    unsigned	count;		/* ref. count for this atom		    */
    unsigned    app_count;      /* ref. count of application visible atoms  */
    const void	*obj_ptr;	/* pointer associated with the atom	    */
    struct H5I_id_info_t *next;	/* link to next atom (in case of hash-clash)*/
} H5I_id_info_t;

/* ID type structure used */
typedef struct {
    unsigned	count;		/*# of times this type has been initialized*/
    unsigned    free_count; /* # of available ID structures awaiting recycling */
    unsigned	reserved;	/*# of IDs to reserve for constant IDs	    */
    unsigned	wrapped;	/*whether the id count has wrapped around   */
    size_t	hash_size;	/*sizeof the hash table to store the IDs in */
    unsigned	ids;		/*current number of IDs held		    */
    unsigned	nextid;		/*ID to use for the next atom		    */
    H5I_free_t	free_func;	/*release object method	    		    */
    unsigned    reuse_ids;  /* whether to reuse returned IDs for this type */
    H5I_id_info_t * next_id_ptr; /* pointer to head of available ID list */
    H5I_id_info_t **id_list;	/*pointer to an array of ptrs to IDs	    */
} H5I_id_type_t;


/*-------------------- Locally scoped variables -----------------------------*/

/* Array of pointers to atomic types */
static H5I_id_type_t *H5I_id_type_list_g[MAX_NUM_TYPES];

/* Variable to keep track of the number of types allocated.  Its value is the */
/* next type ID to be handed out, so it is always one greater than the number */
/* of types. */
/* Starts at 1 instead of 0 because it makes trace output look nicer.  If more */
/* types (or IDs within a type) are needed, adjust TYPE_BITS in H5Ipkg.h       */
/* and/or increase size of hid_t */
static H5I_type_t H5I_next_type = (H5I_type_t) H5I_NTYPES;

/* Declare a free list to manage the H5I_id_info_t struct */
H5FL_DEFINE_STATIC(H5I_id_info_t);

/*--------------------- Local function prototypes ---------------------------*/
static H5I_id_info_t *H5I_find_id(hid_t id);
#ifdef H5I_DEBUG_OUTPUT
static herr_t H5I_debug(H5I_type_t type);
#endif /* H5I_DEBUG_OUTPUT */


/*--------------------------------------------------------------------------
NAME
   H5I_init_interface -- Initialize interface-specific information
USAGE
    herr_t H5I_init_interface()

RETURNS
    Non-negative on success/Negative on failure
DESCRIPTION
    Initializes any interface-specific data or routines.

--------------------------------------------------------------------------*/
static herr_t
H5I_init_interface(void)
{
    FUNC_ENTER_NOAPI_NOINIT_NOFUNC(H5I_init_interface)

    FUNC_LEAVE_NOAPI(SUCCEED)
} /* end H5I_init_interface() */


/*-------------------------------------------------------------------------
 * Function:	H5I_term_interface
 *
 * Purpose:	Terminate the H5I interface: release all memory, reset all
 *		global variables to initial values. This only happens if all
 *		types have been destroyed from other interfaces.
 *
 * Return:	Success:	Positive if any action was taken that might
 *				affect some other interface; zero otherwise.
 *
 * 		Failure:	Negative.
 *
 * Programmer:	Unknown
 *
 *-------------------------------------------------------------------------
 */
int
H5I_term_interface(void)
{
    H5I_id_type_t	*type_ptr;
    H5I_type_t		type;
    int		n = 0;

    FUNC_ENTER_NOAPI_NOINIT_NOFUNC(H5I_term_interface)

    if(H5_interface_initialize_g) {
        /* How many types are still being used? */
        for(type = (H5I_type_t)0; type < H5I_next_type; H5_INC_ENUM(H5I_type_t, type)) {
            if((type_ptr = H5I_id_type_list_g[type]) && type_ptr->id_list)
                n++;
        } /* end for */

        /* If no types are used then clean up */
        if(0 == n) {
            for(type = (H5I_type_t)0; type < H5I_next_type; H5_INC_ENUM(H5I_type_t,type)) {
                type_ptr = H5I_id_type_list_g[type];
                H5MM_xfree(type_ptr);
                H5I_id_type_list_g[type] = NULL;
            } /* end for */
        } /* end if */

        /* Mark interface closed */
        H5_interface_initialize_g = 0;
    } /* end if */

    FUNC_LEAVE_NOAPI(n)
} /* end H5I_term_interface() */


/*-------------------------------------------------------------------------
 * Function:	H5Iregister_type
 *
 * Purpose:	Public interface to H5I_register_type.  Creates a new type
 *		of ID's to give out.  A specific number (RESERVED) of type
 *		entries may be reserved to enable "constant" values to be handed
 *		out which are valid IDs in the type, but which do not map to any
 *		data structures and are not allocated dynamically later. HASH_SIZE is
 *		the minimum hash table size to use for the type. FREE_FUNC is
 *		called with an object pointer when the object is removed from
 *		the type.
 *
 * Return:	Success:	Type ID of the new type
 *		Failure:	H5I_BADID
 *
 * Programmers:	Nathaniel Furrer
 *		James Laird
 *		Friday, April 30, 2004
 *
 *-------------------------------------------------------------------------
 */
H5I_type_t
H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func)
{
    H5I_type_t ret_value;       /* Return value */

    FUNC_ENTER_API(H5Iregister_type, H5I_BADID)
    H5TRACE3("It", "zIux", hash_size, reserved, free_func);

    /* Call H5I_register_type with a value of 0 to get a new type */
    ret_value = H5I_register_type((H5I_type_t)0, hash_size, reserved, free_func);

done:
    FUNC_LEAVE_API(ret_value)
} /* end H5Iregister_type() */


/*-------------------------------------------------------------------------
 * Function:	H5I_register_type
 *
 * Purpose:	Creates a new type of ID's to give out.  A specific number
 *		(RESERVED) of type entries may be reserved to enable "constant"
 *		values to be handed out which are valid IDs in the type, but
 *		which do not map to any data structures and are not allocated
 *		dynamically later. TYPE_ID is the H5I_type_t value of the type
 *		to be initialized.  If this value is zero, a new type is created.
 *		If this value is one of the library types, that type is
 *		initialized or its reference count is incremented (if it is already
 *		initialized).  HASH_SIZE is the minimum hash table size to
 *		use for the type. FREE_FUNC is called with an object pointer
 *		when the object is removed from the type.
 *
 * Return:	Success:	Type ID of the new type
 *		Failure:	H5I_BADID
 *
 * Programmers:	Nathaniel Furrer
 *		James Laird
 *		Friday, April 30, 2004
 *
 *-------------------------------------------------------------------------
 */
H5I_type_t
H5I_register_type(H5I_type_t type_id, size_t hash_size, unsigned reserved,
    H5I_free_t free_func)
{
    H5I_id_type_t	*type_ptr = NULL;		/*ptr to the atomic type*/
    H5I_type_t ret_value = H5I_BADID;                   /* type ID to return */

    FUNC_ENTER_NOAPI(H5I_register_type, H5I_BADID)

    /* Check that type_id is either a library type or zero */
    if(type_id < 0 || type_id >= H5I_NTYPES)
        HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, H5I_BADID, "invalid type ID")

    if(type_id == 0) {	/* Generate a new H5I_type_t value */
        /* Increment the number of types*/
        if(H5I_next_type < MAX_NUM_TYPES) {
            ret_value = H5I_next_type;
            H5_INC_ENUM(H5I_type_t, H5I_next_type);
        }
        else {
            hbool_t done;       /* Indicate that search was successful */
            int i;              /* Local index variable */

            /* Look for a free type to give out */
            done = FALSE;
            for(i = H5I_NTYPES; i < MAX_NUM_TYPES && done == FALSE; i++) {
                if(NULL == H5I_id_type_list_g[i]) {
                    /* Found a free type ID */
                    ret_value = (H5I_type_t)i;
                    done = TRUE;
                } /* end if */
            } /* end for */

            /* Verify that we found a type to give out */
            if(done == FALSE)
                HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, H5I_BADID, "Maximum number of ID types exceeded.")
        } /* end else */
    } /* end if */
    else	/* type_id is a library type; use this value. */
        ret_value = type_id;

    /* Initialize the type */

    /* Check arguments */
#ifdef HASH_SIZE_POWER_2
    if(!POWER_OF_TWO(hash_size) || hash_size == 1)
        HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, H5I_BADID, "invalid hash size")
#endif /* HASH_SIZE_POWER_2 */

    if(NULL == H5I_id_type_list_g[ret_value]) {
        /* Allocate the type information for new type */
        if(NULL == (type_ptr = (H5I_id_type_t *)H5MM_calloc(sizeof(H5I_id_type_t))))
            HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, H5I_BADID, "memory allocation failed")
        H5I_id_type_list_g[ret_value] = type_ptr;
    } /* end if */
    else {
        /* Get the pointer to the existing type */
        type_ptr = H5I_id_type_list_g[ret_value];
    } /* end else */

    if(type_ptr->count == 0) {
        /* Initialize the ID type structure for new types */
        type_ptr->hash_size = hash_size;
        type_ptr->reserved = reserved;
        type_ptr->wrapped = 0;
        type_ptr->ids = 0;
        type_ptr->nextid = reserved;
        type_ptr->free_func = free_func;
        type_ptr->next_id_ptr = NULL;
        type_ptr->id_list = (H5I_id_info_t **)H5MM_calloc(hash_size * sizeof(H5I_id_info_t *));
        if(NULL == type_ptr->id_list)
            HGOTO_ERROR(H5E_RESOURCE, H5E_NOSPACE, H5I_BADID, "memory allocation failed")

        /* Don't re-use IDs for property lists, as this causes problems
         * with some virtual file drivers. Also, open datatypes are not 
         * getting reduced to zero before file close in some situations,
         * resulting in memory leak, so skip them for now as well. */
        if (type_id == H5I_GENPROP_LST || type_id == H5I_DATATYPE)
            type_ptr->reuse_ids = FALSE;
        else
            type_ptr->reuse_ids = TRUE;

    } /* end if */

    /* Increment the count of the times this type has been initialized */
    type_ptr->count++;

done:
    if(ret_value == H5I_BADID) {	/* Clean up on error */
        if(type_ptr != NULL) {
            H5MM_xfree(type_ptr->id_list);
            H5MM_xfree(type_ptr);
        } /* end if */
    } /* end if */

    FUNC_LEAVE_NOAPI(ret_value)
} /* end H5I_register_type() */


/*-------------------------------------------------------------------------
 * Function:	H5Itype_exists
 *
 * Purpose:     Query function to inform the user if a given type is
 *              currently registered with the library.
 *
 * Return:	Success:        1 if the type is registered, 0 if it is not
 *		Failure:	Negative
 *
 * Programmer:	James Laird
 *		Nathaniel Furrer
 *              Tuesday, June 29, 2004
 *
 *-------------------------------------------------------------------------
 */
htri_t
H5Itype_exists(H5I_type_t type)
{
    htri_t ret_value = TRUE;                      /* Return value */

    FUNC_ENTER_API(H5Itype_exists, FAIL)
    H5TRACE1("t", "It", type);

    if(type <= H5I_BADID || type >= H5I_next_type)
	HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number")

    if(NULL == H5I_id_type_list_g[type])
        ret_value = FALSE;

done:
    FUNC_LEAVE_API(ret_value)
} /* end H5Itype_exists() */


/*-------------------------------------------------------------------------
 * Function:	H5Inmembers
 *
 * Purpose:	Returns the number of members in a type.  Public interface to
 *		H5I_nmembers.  The public interface throws an error if the
 *              supplied type does not exist.  This is different than the
 *              private interface, which will just return 0.
 *
 * Return:	Success:	Zero
 *		Failure:	Negative
 *
 * Programmer:	James Laird
 *		Nathaniel Furrer
 *              Friday, April 23, 2004
 *
 *-------------------------------------------------------------------------
 */
herr_t
H5Inmembers(H5I_type_t type, hsize_t *num_members)
{
    int ret_value = SUCCEED;                      /* Return value */

    FUNC_ENTER_API(H5Inmembers, FAIL)
    H5TRACE2("e", "It*h", type, num_members);

    if(H5I_IS_LIB_TYPE(type))
        HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "cannot call public function on library type")

    /* Validate parameters.  This needs to be done here, instead of letting
     * the private interface handle it, because the public interface throws
     * an error when the supplied type does not exist.
     */
    if(type <= H5I_BADID || type >= H5I_next_type)
	HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number")
    if(NULL == H5I_id_type_list_g[type])
	HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "supplied type does not exist")

    if(num_members) {
        int members;

        if((members = H5I_nmembers(type)) < 0)
            HGOTO_ERROR(H5E_ATOM, H5E_CANTCOUNT, FAIL, "can't compute number of members")

        *num_members = (hsize_t)members;
    } /* end if */

done:
    FUNC_LEAVE_API(ret_value)
} /* end H5Inmembers() */


/*-------------------------------------------------------------------------
 * Function:	H5I_nmembers
 *
 * Purpose:	Returns the number of members in a type.
 *
 * Return:	Success:	Number of members; zero if the type is empty
 *				or has been deleted.
 *
 *		Failure:	Negative
 *
 * Programmer:	Robb Matzke
 *              Wednesday, March 24, 1999
 *
 *-------------------------------------------------------------------------
 */
int
H5I_nmembers(H5I_type_t type)
{
    H5I_id_type_t	*type_ptr = NULL;
    int		ret_value;

    FUNC_ENTER_NOAPI(H5I_nmembers, FAIL)

    if(type <= H5I_BADID || type >= H5I_next_type)
	HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number")
    if(NULL == (type_ptr = H5I_id_type_list_g[type]) || type_ptr->count <= 0)
	HGOTO_DONE(0);

    /* Set return value */
    H5_ASSIGN_OVERFLOW(ret_value, type_ptr->ids, unsigned, int);

done:
    FUNC_LEAVE_NOAPI(ret_value)
} /* end H5I_nmembers() */


/*-------------------------------------------------------------------------
 * Function:	H5Iclear_type
 *
 * Purpose:	Removes all objects from the type, calling the free
 *		function for each object regardless of the reference count.
 *		Public interface to H5I_clear_type.
 *
 * Return:	Success:	Non-negative
 *		Failure:	negative
 *
 * Programmer:	James Laird
 *		Nathaniel Furrer
 *              Friday, April 23, 2004
 *
 *-------------------------------------------------------------------------
 */
herr_t
H5Iclear_type(H5I_type_t type, hbool_t force)
{
    herr_t ret_value;                      /* Return value */

    FUNC_ENTER_API(H5Iclear_type, FAIL)
    H5TRACE2("e", "Itb", type, force);

    if(H5I_IS_LIB_TYPE(type))
        HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "cannot call public function on library type")

    ret_value = H5I_clear_type(type, force, TRUE);

done:
    FUNC_LEAVE_API(ret_value)
} /* end H5Iclear_type() */


/*-------------------------------------------------------------------------
 * Function:	H5I_clear_type
 *
 * Purpose:	Removes all objects from the type, calling the free
 *		function for each object regardless of the reference count.
 *
 * Return:	Success:	Non-negative
 *		Failure:	negative
 *
 * Programmer:	Robb Matzke
 *              Wednesday, March 24, 1999
 *
 * Modifications:
 * 		Robb Matzke, 1999-04-27
 *		If FORCE is zero then any item for which the free callback
 *		failed is not removed.  This function returns failure if
 *		items could not be removed.
 *
 * 		Robb Matzke, 1999-08-17
 *		If the object reference count is larger than one then it must
 *		be because the library is using the object internally. This
 *		happens for instance for file driver ID's which are stored in
 *		things like property lists, files, etc.  Objects that have a
 *		reference count larger than one are not affected unless FORCE
 *		is non-zero.
 *
 *      Neil Fortner, 2008-08-08
 *      Added app_ref parameter.  If app_ref is FALSE, then the
 *      application reference count is ignored (i.e. subtracted from
 *      the total reference count) when determining which id's to
 *      close.
 *-------------------------------------------------------------------------
 */
herr_t
H5I_clear_type(H5I_type_t type, hbool_t force, hbool_t app_ref)
{
    H5I_id_type_t *type_ptr;	        /* ptr to the atomic type */
    unsigned	i;                      /* Local index variable */
    int		ret_value = SUCCEED;    /* Return value */

    FUNC_ENTER_NOAPI(H5I_clear_type, FAIL)

    if(type <= H5I_BADID || type >= H5I_next_type)
	HGOTO_ERROR(H5E_ARGS, H5E_BADRANGE, FAIL, "invalid type number")

    type_ptr = H5I_id_type_list_g[type];
    if(type_ptr == NULL || type_ptr->count <= 0)
	HGOTO_ERROR(H5E_ATOM, H5E_BADGROUP, FAIL, "invalid type")

    /*
     * Call free method for all objects in type regardless of their reference
     * counts. Ignore the return value from from the free method and remove
     * object from type regardless if FORCE is non-zero.
     */
    for(i = 0; i < type_ptr->hash_size; i++) {
        H5I_id_info_t *cur;          /* Current node being worked with */
        H5I_id_info_t *next;         /* Next node in list */

        for(cur = type_ptr->id_list[i]; cur; cur = next) {
            hbool_t    delete_node;            /* Flag to indicate node should be removed from linked list */

            /*
             * Do nothing to the object if the reference count is larger than
             * one and forcing is off.
             */
            if(!force && (cur->count - (!app_ref * cur->app_count)) > 1) {
                next = cur->next;
                continue;
            } /* end if */

            /* Check for a 'free' function and call it, if it exists */
            /* (Casting away const OK -QAK) */
            if(type_ptr->free_func && (type_ptr->free_func)((void *)cur->obj_ptr) < 0) {
                if(force) {
#ifdef H5I_DEBUG
                    if(H5DEBUG(I)) {
                        fprintf(H5DEBUG(I), "H5I: free type=%d obj=0x%08lx "
                            "failure ignored\n", (int)type,
                            (unsigned long)(cur->obj_ptr));
                    } /* end if */
#endif /*H5I_DEBUG*/

                    /* Indicate node should be removed from list */
                    delete_node = TRUE;
                } /* end if */
                else {
                    /* Indicate node should _NOT_ be remove from list */
                    delete_node = FALSE;
                } /* end else */
            } /* end if */
            else {
                /* Indicate node should be removed from list */
                delete_node = TRUE;
            } /* end else */

            /* Check if we should delete this node or not */
            if(delete_node) {
                H5I_id_info_t *last;         /* Last node seen */
                H5I_id_info_t *tmp;          /* Temporary node ptr */

                /* Decrement the number of IDs in the type */
                (type_ptr->ids)--;

                /* Advance to next node */
                next = cur->next;