dialogs.h

/* dialogs.h */
/* $Id: dialogs.h,v 1.23 2006/10/18 10:58:57 vlad Exp $ */
#ifndef __dialogs_h
#define __dialogs_h

#include <stdio.h>
#include <X11/Intrinsic.h>
#include <ldb/dbtools.h>

#ifdef __cplusplus
extern "C"
{
#endif /* __cplusplus */

/* Width limit width of dbt dialogs to prevent too width selection box. */
#define ZM_MAX_DBT_DIALOG_WIDTH     120

/* Special codes which can be returned by Zm* functions in emergency. */
#define ZM_CANCEL           (-1)
#define ZM_BAD_CALL         (-2)


/***********************************************************************
 * Generic list dialog. Can select one item from pointed string
 * item set. Returns index of selected string in set (0..) or
 * -1 if cancel is pressed.
 * Input:
 *  Widget parent   -- parent widget;
 *  const char* name    -- dialog name (NULL=>"LSB");
 *  const char* title   -- dialog WM title (NULL=>"Single Selection");
 *  const char* lhead   -- title of list (NULL=>"List");
 *  char** sset     -- selectable set;
 *  int sset_n      -- number of items in sset;
 * Return values:
 *   0 .. sset_n-1 -- index of selected item by Ok;
 *  -1 -- Cancel is pressed;
 *  -2 -- bad primary parameters.
 */
int
ZmListSelectionBox (Widget parent,  /* parent widget */
            const char* name,   /* dialog name */
            const char* title,  /* dialog WM title */
            const char* lhead,  /* title of list */
            char** sset,    /* selectable set */
            int sset_n);    /* number of items in sset */


/***********************************************************************
 * Generic multiple selection list dialog.  Can select one or any number
 * of items from pointed string item set.  Returns numner of selected
 * indeces in set (1..max_sel) or 0 if Cancel is pressed or zero items
 * were selected.
 * Input:
 *  Widget parent   -- parent widget;
 *  const char* name    -- dialog name (NULL=>"MSB");
 *  const char* title   -- dialog WM title (NULL=>"Multiple Selection");
 *  const char* lhead   -- title of list (NULL=>"List");
 *  char** sset     -- selectable set;
 *  int sset_n      -- number of items in sset;
 *  int max_sel     -- max number of items or 0;
 *  int** sel_items     -- array of selected indeces in order
 *                         of selection (dyn. allocated);
 * Return values:
 *  number of items in sel_items
 *   0 -- no items were selected;
 *  -1 -- Cancel is pressed;
 *  -2 -- bad primary parameters.
 */
int
ZmListMultipleSelectionBox (Widget parent,  /* parent widget */
                const char* name,   /* dialog name */
                const char* title,  /* dialog WM title */
                const char* lhead,  /* title of list */
                char** sset,    /* selectable set */
                int sset_n,     /* number of items in sset */
                int max_sel,    /* max number of items or 0 */
                int** sel_items);   /* array of sel.item indeces */


/***********************************************************************
 * Generic list dialog with enter feature.  Can select one
 * item from pointed string item set.  Returns index of
 * selected string in set (0..) or -1 if cancel is pressed.
 * Input:
 *  Widget parent   -- parent widget;
 *  const char* name    -- dialog name (NULL=>"LEB");
 *  const char* title   -- dialog WM title (NULL=>"Single Enter");
 *  const char* lhead   -- title of list (NULL=>"List");
 *  char** sset     -- selectable set;
 *  int sset_n      -- number of items in sset;
 *  char** enter         -- non-matched entered item free(*enter);
 * Return values:
 *  0 .. sset_n-1 -- index of selected item by Ok;
 *  sset_n -- means new value entered in enter;
 *  -1 -- Cancel is pressed;
 *  -2 -- bad primary parameters.
 */
int
ZmListEnterBox (Widget parent,      /* parent widget */
        const char* name,   /* dialog name */
        const char* title,  /* dialog WM title */
        const char* lhead,  /* title of list */
        char** sset,        /* selectable set */
        int sset_n,     /* number of items in sset */
        char** enter);      /* non-matched entered item */


/***********************************************************************
 * Project selection dialog. Project is selected from DATA
 * directory. If selection is OK project is checked for JOBS
 * and LOG existance with EL_WARNING alarm if are not exist.
 * Memory is allocated for selected project by malloc().
 * If no project is selected NULL will be returned.
 */
char*
ZmProjectSelectionBox (Widget parent);  /* parent widget */


/***********************************************************************
 * Data selection dialog.  Data modification is a four chars
 * name that begins with D,R,S.  Other three chars is number
 * xxx.  So, D123, R000, S987 are correct modification names.
 * Filename is mod.name with .dat suffix: D678.dat for example.
 * Modification is two files: Mxxx.tab and [DRS]xxx.dat.
 * Mxxx.dat contains pointer at *.dat file, so xxx must be the
 * same to provide bidirectional relation between them.
 * The function returns [DRS]xxx string.  If Mxxx.tab is not
 * exist or bad, EL_WARNING alarmed through wePutMsg.  So will
 * be if Mxxx.tab does not point to selected string.
 * Memory for returned string is allocated by malloc().
 * If project is NULL current one will be used.
 */
char*
ZmDataSelectionBox (Widget parent,      /* parent widget */
            const char* project);   /* project to select from */


/***********************************************************************
 * Data enter dialog.  Data modification is a four chars
 * name that begins with D,R,S.  Other three chars is number
 * xxx.  So, D123, R000, S987 are correct modification names.
 * Filename is mod.name with .dat suffix: D678.dat for example.
 * Modification is two files: Mxxx.tab and [DRS]xxx.dat.
 * Mxxx.dat contains pointer at *.dat file, so xxx must be the
 * same to provide bidirectional relation between them.
 * The function returns [DRS]xxx string.
 * Memory for returned string is allocated by malloc().
 * If project is NULL current one will be used.
 * def_nmod can be used for default value assignment.  def_nmod
 * can be NULL.
 * */
char*
ZmDataEnterBox (Widget parent,      /* parent widget */
        const char* project,    /* project to select from */
        const char* def_nmod);  /* default value */


/***********************************************************************
 * Data base table selection dialog form db list table.  Any
 * data base list can be used.  It must have "DTBSPTR" domain
 * to store db pointer.  If this domain is not found, NULL will
 * be returned.  dbname must be not null pointer at storage for
 * result db name.
 */
dbNameStruct*
ZmDbtListSelectionBox (Widget parent,       /* parent widget */
               const char* project, /* project to select from */
               const char* dblist,  /* db list to select from */
               dbNameStruct* dbname);   /* place for selected dbtable */


/***********************************************************************
 * Data base table selection dialog from project DATA directory.
 * If dbmask contains right dbt name it is used as filter for
 * directory entries.  For example if dbmask.mask=DB_TABLE and
 * dbmask.table="FBINFO", all files VSP.*.*.FBINFO.* will be
 * placed in selection list.
 * To select all data tables: dbmask.mask=0.
 * To select only db lists: dbmask.mask=DB_LIST.
 * Selected table will be placed in dbmask
 * If project is NULL current one will be used.
 * */
dbNameStruct*
ZmDbtFileSelectionBox (Widget parent,       /* parent widget */
               const char* project, /* project to select from */
               dbNameStruct* dbmask);   /* mask to filter result */


/***********************************************************************
 * Data base table enter dialog from project DATA directory.
 * If dbmask contains right dbt name it is used as filter for
 * directory entries.  For example if dbmask.mask=DB_TABLE and
 * dbmask.table="FBINFO", all files VSP.*.*.FBINFO.* will be
 * placed in selection list.  If user entered db name that does
 * not correcpond to dbmask, cancel with EL_ERROR message will
 * be.
 * To select all data tables: dbmask.mask=0.
 * To select only db lists: dbmask.mask=DB_LIST.
 * Selected or entered table will be placed in dbmask
 * If project is NULL current one will be used.
 */
dbNameStruct*
ZmDbtFileEnterBox (Widget parent,       /* parent widget */
           const char* project,     /* project to select from */
           dbNameStruct* dbmask);   /* mask to filter result */


/***********************************************************************
 * Data base line selection from dbfrom table.  Selected line
 * passed as dbwhere dbItem (dbfrom table and index of line in
 * it).  dbfrom table can be of any type.  Selected item is
 * returned by function or NULL if some errors took place.
 * NULL will be returned if cancel was pressed.  If flag
 * is equal to NEW_DB_ITEM, user can select one additional line
 * that is new item.  Such selection is represented by number
 * of line = -1.
 */
#define ZM_NEW_DB_ITEM      1
dbItem*
ZmDbtItemSelectionBox (Widget parent,       /* parent widget */
               const char* project, /* project to select from */
               dbNameStruct* dbfrom,    /* db table to select from */
               dbItem* dbwhere,     /* place for selected line */
               int flag);       /* NEW_DB_ITEM or 0 */


/***********************************************************************
 * Generic file selection dialog.  Can select or enter one file
 * with full path.  There are some "standard" start directories
 * to provide easy access to project and user directories.
 * Input:
 *  Widget parent   -- parent widget;
 *  const char* name    -- dialog name (NULL=>"FSB");
 *  const char* title   -- dialog WM title (NULL=>"File Selection");
 *  const char* dirspec  -- directory (ZM_CURRENT_DIR,ZM_PROJECT_LOGS,
 *    ZM_PROJECT_JOBS,ZM_PROJECT_DATA,ZM_USER_DEFAULTS or any string);
 *  const char* fmask    -- file mask (* and ? are special) or NULL;
 * Return values:
 *  NULL     -- cancel or bad parameters;
 *  non-NULL -- pointer at full path to selected file to free();
 */
#define ZM_CURRENT_DIR      ((char*)0)
#define ZM_USER_DEFAULTS    ((char*)1)
#define ZM_PROJECT_LOGS     ((char*)2)
#define ZM_PROJECT_JOBS     ((char*)3)
#define ZM_PROJECT_DATA     ((char*)4)
#define ZM_PROJECT_REPORT   ((char*)5)
#define ZM_PROJECT_HCOPIES  ((char*)6)
#define ZM_PROJECT_ARCHIVE  ((char*)7)
#define ZM_USER_HOME        ((char*)8)
#define ZM_SYSTEM_ETC       ((char*)9)
char*
ZmFileSelectionBox (Widget parent,  /* parent widget */
            const char* name,   /* dialog name */
            const char* title,  /* dialog WM title */
            const char* dirspec,/* directory */
            const char* fmask); /* file mask */

char*
ZmPathSpecToPath (const char* szPathSpec);



/***********************************************************************
 * Enter dbt name by parts.
 * Input:
 *  Widget parent      -- parent widget;
 *  const char* name   -- dialog name (NULL=>"DBTNB");
 *  const char* title  -- dialog WM title (NULL=>"Data base table naming");
 *  dbNameStruct* dbns -- partially defined dbt name;  user needs
 *     to define (or redefine) parts of name;
 *  int fixed_mask     -- parts of name not to edit;
 *  int oblig_mask     -- obligatory parts of name to define;
 * Output:
 *  NULL               -- cancel pressed;
 *  non-NULL           -- pointer dbns but with defined parts;
 */
dbNameStruct*
ZmDbtNamingBox (Widget parent,      /* parent widget */
        const char* name,   /* dialog name */
        const char* title,  /* dialog WM title */
        dbNameStruct* dbns, /* partially defined dbt name */
        int fixed_mask,     /* parts of name not to edit */
        int oblig_mask);    /* parts of name to define */


/***********************************************************************
 * Palette selection dialog by name.  Returns dynamically allocated
 * name of the palette which can be used in zcp_get_palette()
 * regarding leading '-' in case of reverted color's order is
 * requested.  Needs zcp_init() called before.  Returns NULL on error.
 */
char*
ZmPaletteSelectionBox (Widget parent,           /* parent widget */
               const char* szDefaultPalette);   /* may be NULL */


/***********************************************************************
 * Color name selection dialog.  Returns name of selected color.
 * Needs zcp_init() called before.  Returns NULL on error.  Returned
 * string is dynamically allocated and must be free() if unused.
 */
char*
ZmColorNameSelectionBox (Widget parent,
             const char* szDefaultColor);


/* Value for dialog type */
typedef enum
{
  ZmDialogSingleSelectionList = 0,
  ZmDialogMultipleSelectionList

}   ZmDialogType;

/* Value for preselect_kind */
typedef enum
{
  ZmPreselectByPos = 0,     /* line index: 0..sset_n-1 */
  ZmPreselectByString,      /* whole line match */
  ZmPreselectByTaggedDbtName    /* match only tagged column */

}   ZmDialogPreselectKind;

/* Custom final widget processing procedure. */
typedef void    (*ZmCustomWidgetProc) (Widget wParent, Widget wTarget);

/* Structure to store customized options */
typedef struct
{
  int           mask;   /* ORed options: ZmDM_* */
  char          *help_section;
  char          *title_string;
  char          *resource_name;
  ZmDialogPreselectKind preselect_kind;
  int           preselect_pos;
  char          *preselect_tag;
  char          *preselect_string;
  dbNameStruct      preselect_dbtname;
  char          *dialog_id; /* id string for this dialog */
  ZmDialogType      dialog_type;
  int           multselect_max; /* max number of selected lines */
  int           *multselect_num;/* number of selected lines */
  void          *multselect_list;/* resulting array of selected items */
  ZmCustomWidgetProc    custom_selbox_proc;/* for SelBox */

}   ZmDialogCustomOptions;

/* Mask for selected customized options */
#define ZmDM_HELP_SECTION   (1<<0)
#define ZmDM_TITLE_STRING   (1<<1)
#define ZmDM_RESOURCE_NAME  (1<<2)
#define ZmDM_PRESELECT_KIND (1<<3)
#define ZmDM_PRESELECT_POS  (1<<4)
#define ZmDM_PRESELECT_TAG  (1<<5)
#define ZmDM_PRESELECT_STRING   (1<<6)
#define ZmDM_PRESELECT_DBTNAME  (1<<7)
#define ZmDM_DIALOG_ID      (1<<8)
#define ZmDM_DIALOG_TYPE    (1<<9)
#define ZmDM_MULTSELECT_MAX (1<<10)
#define ZmDM_MULTSELECT_NUM (1<<11)
#define ZmDM_MULTSELECT_LIST    (1<<12)
#define ZmDM_CUSTOM_SELBOX_PROC (1<<13)

/* Identifiers for customizable options */
typedef enum {
  ZmD_End = 0,          /* end-of-list option */
  ZmD_HelpSection,      /* setup help section */
  ZmD_TitleString,      /* setup window title (English) */
  ZmD_ResourceName,     /* setup resource name */
  ZmD_PreselectKind,        /* what type of preselect?
                 * no preselect by default! */
  ZmD_PreselectTag,     /* match something in column tag */
  ZmD_PreselectPos,     /* preselect line # pos or number of lines */
  ZmD_PreselectString,      /* preselect line which match string */
  ZmD_PreselectDbtName,     /* preselect line which match dbt name */
  ZmD_DialogId,         /* N/A - dialog_id to store state between sessions */
  ZmD_DialogType,       /* single or multiple selection? */
  ZmD_MultselectMax,        /* max number of selected lines */
  ZmD_MultselectNum,        /* number of selected lines */
  ZmD_MultselectList,       /* resulting array of selected items */
  ZmD_CustomSelBoxProc      /* ptr to function called on created SelBox */

}   ZmDialogCustomOptionName;


/* Setup additional parameters for the nearest dialog call.
 * For example, context help facility, customized title etc.
 * Programmer may call this function just before dialog call.
 * WARNING! Not for multithreaded applications! */
void        ZmCustomizeDialog (ZmDialogCustomOptionName dco1, ...);


/* Clear all previous customizable options.
 * For internal usage. */
void        ZmClearCustomOptions ();


/* Get resource name. */
const char* ZmDialogGetResourceName (const char* szGivenRes,
                     const char* szDefaultRes);

/* Setup help.  Return TRUE on success (help is defined) and FALSE
 * otherwise. */
Logic       ZmDialogSetupHelp (Widget wSelBox);

/* Setup title. */
void        ZmDialogSetupTitle (Widget wShell,
                    const char* szGivenTitle,
                    const char* szDefaultTitle);

/* N/A - Prepare (open) file for dialog state saving/retrieving */
FILE*       ZmDialogStateFile (const char* szDialogId,
                   const char* szMode); /* "r" or "w" */


#ifdef __CustomOptionVariable
#define EXTERN
#else /* __CustomOptionVariable */
#define EXTERN  extern
#endif /* __CustomOptionVariable */
EXTERN ZmDialogCustomOptions    rCustomOpt;
#undef EXTERN


#ifdef __cplusplus
};
#endif /* __cplusplus */

#endif /* dialogs.h */