micon.h

Go to the documentation of this file.

/**
 * \file micon.h <mi32/micon.h>
 * \brief Definitions for portable "icon" functions
 *
 * \if NODOC
 * $Id: micon.h_v 1.20 2003/09/25 21:29:07 dwilliss Exp $
 *
 * $Log: micon.h_v $
 * Revision 1.20  2003/09/25 21:29:07  dwilliss
 * Don't capitalize enum any more. Genitor needed it, doxygen doesn't like it.
 *
 * Revision 1.19  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.18  2001/12/20 15:51:18  mju
 * Another Surveyor test.
 *
 * Revision 1.17  2001/12/19 16:04:51  mju
 * Another Surveyor test.
 *
 * Revision 1.11  2001/12/14 18:52:51  mju
 * Add MiconRead which uses ICONID.
 *
 * Revision 1.9  2001/12/04 14:48:33  mju
 * Use enum for MICONFLAGS.
 *
 * Revision 1.8  2000/06/20 20:17:45  sparsons
 * Genitor documentation.
 *
 * Revision 1.1  1999/01/07  23:10:27  mju
 * Initial revision
 * \endif
**/

#ifndef  INC_MI32_MICON_H
#define  INC_MI32_MICON_H

#ifndef  INC_MI32_STDDEFNS_H
   #include <mi32/stddefns.h>
#endif

#ifndef  INC_MI32_ICONID_H
   #include <mi32/iconid.h>
#endif

//----------------------------------------------------------------------------
//    Types and constants                                                     
//----------------------------------------------------------------------------

//! Enumeration for flags used in various Micon functions.
enum MICONFLAGS {
   MICONFLAG_None =              0x0000,  //!< No flags specified
   MICONFLAG_Stippled =          0x0001,  //!< Create a "dimmed" pixmap as well as a normal pixmap
   MICONFLAG_DefaultBackground = 0x0002,  //!< Use MxTopLevel()'s XmNbackground resource
   MICONFLAG_StippledSelected =  0x0008,  //!< Create "dimmed" pixmap for armed/selected state
   MICONFLAG_SizeMask =          0x0FF0,  //!< Bit mask for sizes from 1 to 255
   MICONFLAG_Size16 =            0x0100,  //!< Resize icon to 16 by 16 if smaller
   MICONFLAG_Size32 =            0x0200,  //!< Resize icon to 32 by 32 if smaller
   MICONFLAG_NoDarkenSelected =  0x1000,  //!< Don't darken background for "selected" state
   MICONFLAG_DisplayError =      0x2000,  //!< Display icon reading error even in non-programmer mode
   };
DEFINE_ENUM_OPERATORS(MICONFLAGS);


struct MICONSTRUCT {
   UNICODE group[16];
   UNICODE name[16];
   UINT8 height;
   UINT8 width;
   UINT8 resized;
   UINT8 spare;                        //!< For alignment
   UINT32 refcount;
   MPIXEL bgpixel;                     //!< Background pixel
   void *privptr;
   };
typedef MICONSTRUCT *MICON;


//----------------------------------------------------------------------------
//    Function prototypes                                                     
//----------------------------------------------------------------------------

// Note, these functions use C++ linkage.

//!:Associate with "Micon Functions"
//!\addtogroup Micon Micon functions
//!@{

//! Create new icon.
//!
//! Flags:
//!      MICONFLAG_DefaultBackground   Use MxTopLevel()'s XmNbackground resource
//!      MICONFLAG_SizeMask            Bit mask for sizes from 1 to 255 
//!      MICONFLAG_Size16              16 by 16
//!      MICONFLAG_Size32              32 by 32
//!      MICONFLAG_Stippled            Create a "dimmed" pixmap as well as a normal pixmap
int MiconCreate (
   MICON *icon,                        //!< Icon returned
   int ihandle,                        //!< Icon group handle (0 for standard file)
   const UNICODE *group,               //!< Icon group name
   const UNICODE *name,                //!< Icon name
   MPIXEL bgpixel,                     //!< Background pixel
   UINT8 width,                        //!< Icon width (0 to use value from file)
   UINT8 height,                       //!< Icon height (0 to use value from file)
   UINT32 flags                        //!< Flags 
   );

//! Create new icon.
//!
//! Flags:
//!      MICONFLAG_DefaultBackground   Use MxTopLevel()'s XmNbackground resource
//!      MICONFLAG_SizeMask            Bit mask for sizes from 1 to 255 
//!      MICONFLAG_Size16              16 by 16
//!      MICONFLAG_Size32              32 by 32
//!      MICONFLAG_Stippled            Create a "dimmed" pixmap as well as a normal pixmap
int MiconCreate (
   MICON *icon,                        //!< Icon returned
   const char *group,                  //!< Icon group, NULL for "standard"
   const char *name,                   //!< Icon name
   MPIXEL bgpixel,                     //!< Background pixel
   UINT8 width,                        //!< Icon width (0 to use value from file)
   UINT8 height,                       //!< Icon height (0 to use value from file)
   UINT32 flags                        //!< Flags
   );

//! Destroy icon.
void MiconDestroy (
   MICON icon                          //!< Icon to destroy
   );

//! Get icon height in pixels.
inline UINT8 MiconGetHeight (
   const MICON icon                    //!< Icon to use
   ) { return (icon->height); }

//! Get icon width in pixels.
inline UINT8 MiconGetWidth (
   const MICON icon                    //!< Icon to use
   ) { return (icon->width); }

//! Close icon group.
void MiconGroupClose (
   int ihandle                         //!< Icon group handle
   );

//! Open icon group.
//! @return Icon handle or error < 0.
int MiconGroupOpen (
   const UNICODE *filename,            //!< Icon file name, NULL for "icons.ref"
   const UNICODE *group                //!< Icon group name
   );

//! Read icon as bitmap pattern.
int MiconReadPattern (
   int ihandle,                        //!< Icon group handle
   INT32 pattnum,                      //!< Pattern number if known
   const UNICODE *name,                //!< Icon name
   int width,                          //!< Width, 0 for value from file
   int height,                         //!< Height, 0 for value from file
   void **pattdata                     //!< Pattern buffer allocated and returned
   );

//! Read icon(s) in standard format for use with widget.
//!
//! Flags:
//!      MICONFLAG_DefaultBackground   Use MxTopLevel()'s XmNbackground resource
//!      MICONFLAG_NoDarkenSelected    Don't darken background for "armed/selected" state
//!      MICONFLAG_SizeMask            Bit mask for sizes from 1 to 255 
//!      MICONFLAG_Size16              16 by 16
//!      MICONFLAG_Size32              32 by 32
//!      MICONFLAG_Stippled            Create a "dimmed" pixmap as well as a normal pixmap
int MiconReadStandard (
   int ihandle,                        //!< Icon group handle, 0 for standard file
   const char *group,                  //!< Icon group, NULL for "standard"
   const char *name,                   //!< Icon name
   MICON *normalicon,                  //!< Icon with "normal" colors returned, NULL if don't need
   MICON *armselicon,                  //!< Icon with "armed/selected" colors returned, NULL if don't need
   MPIXEL normalbg,                    //!< Normal background pixel if default not used
   MPIXEL armselbg,                    //!<  Armed/selected background pixel if default not used
   UINT32 flags                        //!< Flags
   );

//! Read icon(s) in standard format for use with widget.
//!
//! Flags:
//!      MICONFLAG_DefaultBackground   Use MxTopLevel()'s XmNbackground resource
//!      MICONFLAG_NoDarkenSelected    Don't darken background for "armed/selected" state
//!      MICONFLAG_SizeMask            Bit mask for sizes from 1 to 255 
//!      MICONFLAG_Size16              16 by 16
//!      MICONFLAG_Size32              32 by 32
//!      MICONFLAG_Stippled            Create a "dimmed" pixmap as well as a normal pixmap 
int MiconReadStandard (
   int ihandle,                        //!< Icon group handle, 0 for standard file
   const char *group,                  //!< Icon group, NULL for "standard"
   const char *name,                   //!< Icon name
   MICON *normalicon,                  //!< Icon with "normal" colors returned, NULL if don't need
   MICON *armeselicon,                 //!< Icon with "armed/selected" colors returned, NULL if don't need
   UINT32 flags                        //!< Flags
   );

//! Read icon for use with widget.
ERRVALUE MiconRead (
   ICONID iconid,                      //!< Icon ID
   MICON *normalicon,                  //!< Icon with "normal" colors returned, NULL if don't need
   MICON *armselicon,                  //!< Icon with "armed/selected" colors returned, NULL if don't need
   MICONFLAGS flags                    //!< Flags
   );

//! Read icon for use with widget with background pixel override.
ERRVALUE MiconRead (
   ICONID iconid,                      //!< Icon ID
   MICON *normalicon,                  //!< Icon with "normal" colors returned, NULL if don't need
   MICON *armselicon,                  //!< Icon with "armed/selected" colors returned, NULL if don't need
   MPIXEL normalbg,                    //!< Normal background pixel if default not used
   MPIXEL armselbg,                    //!<  Armed/selected background pixel if default not used
   MICONFLAGS flags                    //!< Flags
   );

//!@}

#endif   //!< INC_MI32_MICON_H

---