mxdbedit.h

Go to the documentation of this file.

/**
 * \file mxdbedit.h <mi32/mxdbedit.h>
 * \brief Definitions for database editor dialogs
 *
 * Note, most of the functions in this function group are just wrappers
 * around methods of the class DBEDIT.  It is suggested you use the
 * class methods instead of the functions.
 *
 * \if NODOC
 * $Id: mxdbedit.h_v 1.15 2004/04/12 16:08:43 scowan Exp $
 *
 * $Log: mxdbedit.h_v $
 * Revision 1.15  2004/04/12 16:08:43  scowan
 * Added deprecated to certain defined to create warning about the functions being deprecated.
 *
 * Revision 1.14  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.13  2001/12/31 17:49:13  mju
 * Remove comment about flags moved from mxdialog.h.
 *
 * Revision 1.12  2001/12/27 23:30:45  dwilliss
 * Mike undefined a bunch of our constants in WIN32_NATIVE.  Put em back!
 *
 * Revision 1.11  2001/07/25 17:46:30  mju
 * Make DBVIEW_... flags an enum.
 *
 * Revision 1.10  2001/07/25 17:27:12  dwilliss
 * *** empty log message ***
 *
 * Revision 1.9  2001/04/18 21:59:25  dwilliss
 * Changed return type of one function to MDLGPARENT so it would compile for
 * WIN32_NATIVE
 *
 * Revision 1.8  2000/08/08 19:47:58  scowan
 * Fixed elemtype stuff.
 *
 * Revision 1.7  2000/07/07 19:39:09  sparsons
 * Genitor documentation.
 *
 * Revision 1.6  2000/06/01 17:51:23  dwilliss
 * comments
 *
 * Revision 1.5  2000/04/12 22:35:58  dwilliss
 * Added autocomplete callback reason
 *
 * Revision 1.4  1999/10/20 20:35:17  dwilliss
 * Made another function take a const filename
 *
 * Revision 1.3  1999/10/20 19:47:08  mju
 * Make DatabaseEditorCreate take const filename.
 *
 * Revision 1.2  1999/05/26  21:58:31  dwilliss
 * Ifdef out a prototype that didn't work under WIN32_NATIVE
 *
 * Revision 1.1  1999/05/06 22:17:06  mju
 * Initial revision
 *
 * \endif
**/

#ifndef  INC_MI32_MXDBEDIT_H
#define  INC_MI32_MXDBEDIT_H

#ifndef  INC_MI32_MXDIALOG_H
   #include <mi32/mxdialog.h>
#endif

#ifndef  INC_MI32_ELEMTYPE_H
   #include <mi32/elemtype.h>
#endif


//! Flags for database table viewer.
enum DBVIEWFLAGS {
   DBVIEWFLAG_None =                0,
   DBVIEW_ViewActive =              0x00000001, //!< Default to viewing active
   DBVIEW_ViewSelected =            0x00000002, //!< Default to viewing Selected
   DBVIEW_ViewAll =                 0x00000004, //!< Default to viewing all records
   DBVIEW_NoChangeViewMode =        0x00000008, //!< Don't let user change view mode (attached/selected/all)
   DBVIEW_NoSingleRecordView =      0x00000010, //!< Don't allow user to switch to single-record view
   DBVIEW_NoRecordSelection =       0x00000020, //!< Omit record selection buttons
   DBVIEW_NoAttachmentIndicator =   0x00000040, //!< Omit record attachment indicators
   DBVIEW_NoRowControls =           (DBVIEW_NoRecordSelection|DBVIEW_NoAttachmentIndicator),
   DBVIEW_NoNewRecord =             0x00000080, //!< Don't allow user to add new record
   DBVIEW_NoDropTable =             0x00000100, //!< Don't allow user to "drop" table
   DBVIEW_NoEditDefn =              0x00000200, //!< Don't allow user to edit table definition
   DBVIEW_TabularView =             0x00000400, //!< Use tabular view
   DBVIEW_NoElementSelection =      0x00000800, //!< Leave off element selection button row
   DBVIEW_NoCreateIfNotExist =      0x00001000  //!< For MxdDatabaseEditorGetTableInstanceHandle()
   };
DEFINE_ENUM_OPERATORS(DBVIEWFLAGS);


struct MxdDatabaseEditorCallbackStruct {
   UINT32 reason;
   MXDHANDLE dhandle;
   ELEMTYPE ElemType;
   INT32 table;                        //!<  will be inode for form open/close 
   int record;
   INT32 *list;                        //!<  List of records or elements (depending on reason) 
                                       /* DO NOT FREE */
   int num;                            //!<  Number of things in above list 
   unsigned AllFieldsFilledIn:1,
       SpareBits:31;
   };


/* 
** Database editor Callback reasons 
** Note:  The ones defined in terms of MxdCR flags are for backward
**   compatability.
*/
   //! NOTE: The ones that were defined in terms of MxdCR flags won't work
   //! in WIN32_NATIVE because those aren't defined anymore.  So I just
   //! changed them to use the actual values that those constants represent
   //! They're the 4 with high values.
#define MxdDATABASE_Open               0x20000000
#define MxdDATABASE_Close              0x40000000
#define MxdDATABASE_TableOpen          0x0001
#define MxdDATABASE_TableClose         0x0002
#define MxdDATABASE_FormOpen           0x0004
#define MxdDATABASE_FormClose          0x0008
#define MxdDATABASE_Destroy            0x80000000
#define MxdDATABASE_Modify             0x04000000
#define MxdDATABASE_SelectElements     0x0010
#define MxdDATABASE_UnselectElements   0x0020
#define MxdDATABASE_ToggleElements     0x0040
#define MxdDATABASE_SelectOnly         0x0080
#define MxdDATABASE_Elements           0x00F0      //!<  any of the 4 above 
#define MxdDATABASE_FormObjectCreate   0x0100      //!<  A form object has been created under this database 
#define MxdDATABASE_FormObjectDestroy  0x0200      //!<  A form object under this database has been destroyed 
#define MxdDATABASE_AutoComplete       0x0400      

/*----------------------------------------------------------------------------*/
/*    Flags used by MxdDatabaseEditorXxxx functions                           */
/*----------------------------------------------------------------------------*/

#define MxdDATABASE_Clear                 0x00000001  //!<  flag for ...MultiSelectStart 
#define MxdDATABASE_DontUpdateDialogs     0x00000002  //!<  flag for ...MultiSelectEnd 
#define MxdDATABASE_AutoSave              0x00000004  //!<  MxdDatabaseEditorGenViewSaveRecord: Save without prompting 

/* Special Element numbers to pass to MxdDatabaseSetElement...() */
#define MxdDATABASE_DefaultElementList    ELEMENTNUM_DefaultList
#define MxdDATABASE_NoElement             ELEMENTNUM_None


#if defined(__cplusplus)
extern "C" {
#endif

//!:Associate with "DBEDIT"
//!\addtogroup DBEDIT Database Editor
//!@{

//! Add a callback.
//!
//! Valid reasons:      
//!      \li \b MxdDATABASE_Open                Same as MxdCR_Open
//!      \li \b MxdDATABASE_Close               Same as MxdCR_Close
//!      \li \b MxdDATABASE_Destroy             Same as MxdCR_Destroy
//!      \li \b MxdDATABASE_Modify           Same as MxdCR_Modify
//!      \li \b MxdDATABASE_TableOpen        A table window was opened
//!      \li \b MxdDATABASE_TableClose          A table window was closed
//!      \li \b MxdDATABASE_SelectElements   User clicked multiselect button
//!      \li \b MxdDATABASE_UnselectElements User clicked unselect button
//!      \li \b MxdDATABASE_ToggleElements      User clicked toggle select button
//!      \li \b MxdDATABASE_SelectOnly       User clicked exclusive select button
//!      \li \b MxdDATABASE_Elements            The 4 element select reasons or'd together
int MxdDatabaseEditorAddCallback (
   MXDHANDLE dhandle, 
   void (*func)(MxdDatabaseEditorCallbackStruct *,void*), 
   void *data, 
   UINT32 reason
   );

//! Remove a callback.
void MxdDatabaseEditorRemoveCallback (
   MXDHANDLE dhandle, 
   void (*func)(MxdDatabaseEditorCallbackStruct *, void*), 
   void *data, 
   UINT32 reason
   );

//! Create "database editor" dialog.
//!
//! Note, this function no longer opens a dialog of its own.  However,
//!   the dhandle returned must be passed to the other MxdDatabaseEditor functions.
int MxdDatabaseEditorCreate (
   Widget pwidget,                     //!< Parent widget
   MXDHANDLE *dhandle,                 //!< Dialog handle returned
   const UNICODE *fname,               //!< Filename of database
   RVCINODENUM inode,                        //!< Inode of database or database's parent object
   ELEMTYPE elemtypes,                    //!< ELEMTYPE_Xxx of database. 
   UINT32 flags                        //!< Flags
   );

//! Destroy previously created "database editor" dialog.
int MxdDatabaseEditorDestroy (
   MXDHANDLE dhandle
   );

//! Drop a table.
//!
//! Returns 0 or an error < 0, including EUserCancel if the user changes
//!   their mind.  If you don't want to ask the user about dropping the table,
//!   just call MfDropTable directly.  Don't even think about calling this for
//!   an internal table.
int MxdDatabaseEditorDropTable (
   MXDHANDLE dhandle,                  //!< Handle created by MxdDatabaseEditorCreate()
   Widget parent,                      //!< Parent widget for "Are you sure" dialog
   int TableNum,                       //!< Table number to drop
   UINT32 flags                        //!< Flags
   );

//! Drop a form.
//!
//! Returns 0 or an error < 0, including EUserCancel if the user changes
//!   their mind.  If you don't want to ask the user about dropping the table,
//!   just call MfDropTable directly.  Don't even think about calling this for
//!   an internal table.
int MxdDatabaseEditorDropForm (
   MXDHANDLE dhandle,                  //!< Handle created by MxdDatabaseEditorCreate()
   Widget parent,                      //!< Parent widget for "Are you sure" dialog
   INT32 inode,                        //!< Inode of form to delete
   UINT32 flags                        //!< Flags
   );

 //! Popup dialog to edit a table definition. 
int MxdDatabaseEditorEditTableDefn (
   MXDHANDLE dhandle,                  //!< XXX Should be a DBEDIT*
   Widget parent, 
   int TableNum, 
   UINT32 flags
   );

//! Write any changes that havn't been written yet.
int MxdDatabaseEditorFlush (
   MXDHANDLE dhandle                   //!< Handle created by MxdDatabaseEditorCreate()
   );

#ifndef WIN32_NATIVE

//! Create a generic view form for a table.
int MxdDatabaseEditorGenViewCreate (
   MXDHANDLE dhandle,                  //!< Handle created by MxdDatabaseEditorCreate()
   INT32 TableNum,                     //!< Table number
   Widget parent,                      //!< Parent widget for the form that will be created
   Widget *pwidget,                    //!< Form RETURNED
   Arg *arg,                           
   int numargs,                        //!< Number of arguments
   UINT32 flags                        //!< Flags
   );

#endif

//! Destroy a generic view form for a table.
//!
//! Normal people would just destroy the widget.  It's destroy callback will
//!   take care of everything.
int MxdDatabaseEditorGenViewDestroy (
   Widget form                         //!< The form returned by MxdDAtabaseEditorGenViewCreate
   );

//! Add a callback to a GenView.
int MxdDatabaseEditorGenViewAddCallback (
   Widget mainform,                                      //!< Form created from DBEDIT::GenViewCreate()
   void (*)(MxdDatabaseEditorCallbackStruct *, void *),  
   void *data, 
   UINT32 reason
   );

//! Remove a callback from a GenView.
int MxdDatabaseEditorGenViewRemoveCallback (
   Widget mainform,                                      //!< Form created from DBEDIT::GenViewCreate()
   void (*)(MxdDatabaseEditorCallbackStruct *, void *), 
   void *data, 
   UINT32 reason
   );

//! Get the record data for a GenView.
int MxdDatabaseEditorGenViewGetData (
   Widget mainform,                    //!< Form created from DBEDIT::GenViewCreate()
   void *buf                           //!< Buffer to copy data into
   );

//! Set the record data for a GenView.
int MxdDatabaseEditorGenViewSetData (
   Widget mainform,                    //!< Form created from DBEDIT::GenViewCreate()
   void *buf
   );

//! Read a record and set the GenView's data.
int MxdDatabaseEditorGenViewSetRecord (
   Widget mainform,                    //!< Form created via DBEDIT::GenViewCreate()
   INT32 record, 
   UINT32 flags
   );

//! Save the contents of a GenView to a record.
//!
//! It will write whatever record was read via MxdDatabaseEditorGenViewSetRecord().
int MxdDatabaseEditorGenViewSaveRecord (
   Widget mainform,                    //!< Form created via DBEDIT::GenViewCreate()
   UINT32 flags                        //!< Pass MxdDATABASE_AutoSave to avoid "Do you want to save?" dialog
   );

//! Return the database object handle.
int MxdDatabaseEditorGetDBHandle (
   MXDHANDLE dhandle
   );

//! Returns the number of table windows currently open.
//!
//! @return Error code if < 0, Number of open table windows if >= 0.
int MxdDatabaseEditorGetNumOpen (
   MXDHANDLE dhandle                   //!< Handle created by MxdDatabaseEditorCreate()
   );

//! Obsolete:  Use DBEDIT::GetParent().
//! \deprecated  Use DBEDIT::GetParent().
DEPRECATED MDLGPARENT MxdDatabaseEditorGetParent (
   MXDHANDLE dhandle
   );

//! Obsolete: Use DBEDIT::GetTableInstanceHandle().
//! \deprecated Use DBEDIT::GetTableInstanceHandle().
DEPRECATED MXDHANDLE MxdDatabaseEditorGetTableInstanceHandle (
   MXDHANDLE dhandle, 
   INT32 TableNum, 
   UINT32 flags
   );

#ifndef GENERATING_DOXYGEN_OUTPUT
void *_MxdDatabaseEditorGetDBRelateHandle (
   MXDHANDLE dhandle
   );

void _MxdDatabaseEditorSetDBRelateHandle (
   MXDHANDLE dhandle, 
   void *handle
   );
#endif //!< GENERATING_DOXYGEN_OUTPUT

//! Obsolete:  Use DBEDIT::ModalSingleRecordView(). 
//! \deprecated  Use DBEDIT::ModalSingleRecordView(). 
DEPRECATED int MxdDatabaseEditorModalSingleRecordView (
   MXDHANDLE dhandle, 
   INT32 TableNum, 
   INT32 Record, 
   void *initvals,                     //!< Buffer to initialize as (only for Record < 0)
   Widget parent, 
   UINT32 flags
   );

//! Begin selection of multiple elements.
//!
//! Starts the selection of multiple elements.  This function clears the list of selected elements first
//!   if MxdDATABASE_Clear is passed, otherwise it just adds to the list.
//!   See MxdDatabaseEditorSetElement() for more information.
//!   
//!   Flags:   
//!      \b MxdDATABASE_Clear       Clear the list first
int MxdDatabaseEditorMultiSelectStart (
   MXDHANDLE dhandle,                  //!< Dialog handle
   UINT32 flags                        //!< Flags
   );

//! End selection of multiple elements.
//!
//! Ends the selection of multiple elements and updates open tables.
//! See MxdDatabaseEditorSetElement() for more information. 
//!
//!   Flags:
//!      \b MxdDATABASE_DontUpdateDialogs    Don't update table dialogs
int MxdDatabaseEditorMultiSelectEnd (
   MXDHANDLE dhandle,                  //!< Dialog handle
   UINT32 flags                        //!< Flags
   );

//! Popup dialog to create a new table. 
int MxdDatabaseEditorNewTable (
   MXDHANDLE dhandle,                  //!< XXX Should be a DBEDIT*
   Widget parent, 
   UINT32 flags
   );

//! Check the source and see if the function actually exists, if so, it creates a new form.
int MxdDatabaseEditorNewForm (
   MXDHANDLE dhandle,                  //!< XXX Should be a DBEDIT*
   Widget parent,                      //!< Parent widget
   INT32 *inodep,                      //!< Form inode number RETURNED
   UINT32 flags
   );

//! Open a database table window.
//!
//! Most flags are only used by tabular view mode. 
//! Valid flags are:
//!      \li \b DBVIEW_TabularView           Bring window up in Tabular view mode (default is single record view)
//!      \li \b DBVIEW_ViewActive            View Active element's records
//!      \li \b DBVIEW_ViewSelected          View records attached to all selected elements
//!      \li \b DBVIEW_ViewAll               View all records
//!      \li \b DBVIEW_NoChangeViewMode      Don't let user change active/selected/all mode
//!      \li \b DBVIEW_NoSingleRecordView    Don't let user change single record/tabular view mode
//!      \li \b DBVIEW_NoRecordSelection  
//!      \li \b DBVIEW_NoAttachmentIndicator
//!      \li \b DBVIEW_NoRowControls         The two flags above OR'd together      
//!      \li \b DBVIEW_NoNewRecord
//!      \li \b DBVIEW_NoDropTable
//!      \li \b DBVIEW_NoEditDefn 
int MxdDatabaseEditorOpenTableWindow (
   MXDHANDLE dhandle, 
   INT32 table, 
   UINT32 flags
   );

//! Open a database Form window.
int MxdDatabaseEditorOpenFormWindow (
   MXDHANDLE dhandle,                  //!< Dialog handle
   INT32 inode,                        //!< Form inode (must be subobject of database)
   UINT32 flags                        //!< Flags
   );

//! Open tabluar view in database editor.
int MxdDatabaseEditorOpenTabularView (
   MXDHANDLE dhandle, 
   INT32 table, 
   UINT32 flags
   );

//! Close a table window.
int MxdDatabaseEditorCloseTableWindow (
   MXDHANDLE dhandle, 
   INT32 table
   );

//! Close a database Form window.
int MxdDatabaseEditorCloseFormWindow (
   MXDHANDLE dhandle,                  //!< Dialog handle
   INT32 inode                         //!< Form inode (must be subobject of database)
   );

//! Stop updating dialogs.
//!
//! This is useful if you're going to be modifing the database over and over.
int MxdDatabaseEditorSuspendUpdates (
   MXDHANDLE dhandle,                  //!< Dialog handle
   UINT32 flags                        //!< Flags
   );

//!  Open the database relationship (tree view) editor.
int MxdDatabaseEditorRelate (
   MXDHANDLE dhandle,                  //!< XXX Should be a DBEDIT*
   UINT32 flags                        //!< MxdFLAGs
   );

//! Resume updating dialogs.
int MxdDatabaseEditorResumeUpdates (
   MXDHANDLE dhandle,                  //!< Dialog handle
   UINT32 flags                        //!< Flags
   );

//! Refresh the active element attachments. 
int MxdDatabaseEditorRefreshActiveElementAttachments (
   MXDHANDLE dhandle, 
   UINT32 flags
   );

//! Make the database editor figure out what's attached again.
//!
//! Mostly obsolete.  Now everything is done by callbacks and it knows to
//!   update automatically.  However, if you're doing a lot of changes, it's a
//!   good idea to call MxdDatabaseEditorSuspendUpdates() and MxdDatabaseEditorResumeUpdates().
//!
//! Flags:     
//!   \li \b MxdDATABASE_DontUpdateDialogs
int MxdDatabaseEditorRefreshAttachments (
   MXDHANDLE dhandle,                  //!< Handle created by MxdDatabaseEditorCreate()
   UINT32 flags
   );

//! View records attached to a given element.
//!
//! This function is used to change the "Active" element without changing the selected element list.
//! Flags:
//!   \li \b MxdDATABASE_DontUpdateDialogs      Don't update table dialogs
int MxdDatabaseEditorSetActiveElement (
   MXDHANDLE dhandle,                  //!< Handle created by MxdDatabaseEditorCreate()
   INT32 table,                        
   INT32 element,                      //!< Element number to view records for
   ELEMTYPE elemtype,                        //!< ELEMTYPE_Xxxx
   UINT32 flags                        //!< Flags
   );

//! Update the database editor dialogs.
int MxdDatabaseEditorUpdateDialogs (
   MXDHANDLE dhandle
   );

//! Open style dialog.
int MxdDatabaseEditorOpenStyleDialog (
   MXDHANDLE dhandle, 
   Widget parent, 
   UINT32 flags
   );

//! Close style dialog.
int MxdDatabaseEditorCloseStyleDialog (
   MXDHANDLE dhandle
   );

//! Set parent for database editor.
void MxdDatabaseEditorSetParent (
   MXDHANDLE dhandle, 
   Widget widget
   );

//! Set style object for the database editor.
int MxdDatabaseEditorSetStyleObject (
   MXDHANDLE dhandle,                  //!< Dialog handle
   const UNICODE *fname,               //!< Style object filename
   INT32 inode,                        //!< Style object inode
   int styletable,                     //!< Active Style Assignment Table
   void *dftstyle                      //!< Default style (POINTSTYLE/LINESTYLE/POLYSTYLE)
   );

//! Set style handle for the database editor.
int MxdDatabaseEditorSetStyleNumber (
   MXDHANDLE dhandle, 
   int StyleNum, 
   int RecNum, 
   UINT32 flags
   );

//! View records attached to a given element.
//!
//! @return Error code if < 0, 1 if dialog open, 0 if dialog not open.
//!
//!   This function causes the database editor to look up the records attached and related to the 
//! selected element and update the open database windows accordingly.  To set multiple elements, 
//! (for a multi-select tool), call MxdDatabaseEditorMultiSelectStart(), then call 
//! MxdDatabaseEditorSetElement() once for each element, then call MxdDatabaseEditorMultiSelectEnd().
int MxdDatabaseEditorSetElement (
   MXDHANDLE dhandle,                  //!< Handle created by MxdDatabaseEditorCreate()
   INT32 element,                      //!< Element number to view records for
   ELEMTYPE elemtype                //!< ELEMTYPE_Xxxx
   );

//! Set multiple elements for the database editor.
//!
//! Flags:     
//!      \li \b MxdDATABASE_DontUpdateDialogs      Don't update table dialogs
int MxdDatabaseEditorSetElementsExt (
   MXDHANDLE dhandle,                  //!< Handle created by MxdDatabaseEditorCreate()
   ELEMTYPE ElemType,                        //!< ELEMTYPE_Xxxx
   INT32 table,                        
   UINT8 *bits,                        //!< Bit array of selected elements
   INT32 NumElements,                  //!< Size of "Bits" array 
   INT32 ActiveElement,                //!< The "Active" element number
   UINT32 flags                        //!< Flags
   );

//! Set the current element for pin-mapping.
//!
//! This function is the same as MxdDatabaseEditorSetElement, but is used for pin-mapping.
//!   Table is the main table that controls the display.
int MxdDatabaseEditorSetRecord (
   MXDHANDLE dhandle,                  
   int table, 
   INT32 record
   );

//! Check to see if a table is open.
//!
//! Returns a non-zero value if the table is open.  Don't assume it
//!   returns 1 or 0.  Some day, it may be changed to return a value
//!   telling what mode (Single Record or Tabular View) 
int MxdDatabaseEditorTableIsOpen (
   MXDHANDLE dhandle,                  
   int TableNum
   );

//! Inform the database editor that element is unselected.
//!
//! This function has the opposite effect as MxdDatabaseEditorSetElement().  It removes the specified
//!   element from the list of selected elements.  It's meant to be called in a multi-selection situation
//!   only.
int MxdDatabaseEditorUnsetElement (
   MXDHANDLE dhandle,                  
   INT32 element, 
   int otype                           //!< ELEMTYPE_Xxxx
   );

#define  MxdDatabaseEditorSetOpenCallback(h,f,d) MxdDatabaseEditorAddCallback(h,f,d,MxdDATABASE_Open);
#define  MxdDatabaseEditorSetCloseCallback(h,f,d) MxdDatabaseEditorAddCallback(h,f,d,MxdDATABASE_Close);
#define  MxdDatabaseEditorSetModifyCallback(h,f,d) MxdDatabaseEditorAddCallback(h,f,d,MxdDATABASE_Modify);
#define  MxdDatabaseEditorSetDestroyCallback(h,f,d) MxdDatabaseEditorAddCallback(h,f,d,MxdDATABASE_Destroy);
#define  MxdDatabaseEditorSetSelectionCallback(h,f,d) MxdDatabaseEditorAddCallback(h,f,d,MxdDATABASE_Elements);

//!@}

#if defined(__cplusplus)
}
#endif

#endif   //!< INC_MI32_MXDBEDIT_H

---