Indice
Introduzione
Il pacchetto CMENU e' stato creato con i seguenti obiettivi:
- gestire facilmente menu da linguaggio C e da shell
- consentire di creare menu configurabili con file testo
Il pacchetto CMENU e' costituito da una libreria cmenulib e da un programma cmenu.
Realizzazione
CMENU e' stato realizzato in linguaggio C.
Il parser del linguaggio e' stato realizzato con LEX/YACC.
Presentazione
Cmenu e' un Menu Manager che gestisce:
- Menubars and Menus
- Arrays
- SpreadSheet
- Programming language
- ...e molto altro (editor, hex editor, system navigator,...)
Cmenu e' portabile su:
- UNIX (hp,ibm,sco,...)
- MS-DOS
E' portabile in generale su qualsiasi Unix con le librerie Curses.
Cmenu e' utilizzabile in 2 modi:
- dal linguaggio 'C' usando la libreria libcmenu.a
- dalla shell con il programma cmenu
Cmenu ti permette:
- rendere facile ogni operazione
- utilizzare una descrizione testuale dei menu
- portare su ogni piattaforma i tuoi menu (...salvando tempo e denaro)
Programma Cmenu
CMENU e' il programma che legge un file contenente la descrizione di un menu e lo attiva.
Utilizzo
cmenu [-R row|-C col|-M max] [-p|-h|-b|-m|-a] [file]
-p print to stdout the cmenu syntax
-m run menu from file
-b run menubar from file
-h print this help
Examples:
cmenu run menu from file ./cmenu.m
cmenu mybar run menubar from file ./mybar
cmenu -b mybar run menubar from file ./mybar
cmenu -m mymenu run menu from file ./mymenu
cmenu -a array run array from file ./array
cmenu -p >cmenu.m create base menu
Esempi di chiamata
Attivazione di una menubar:
cmenu -b menubar.b
Attivazione di un menu:
cmenu -m array.m
Attivazione di un array:
cmenu -a array.a
Libreria Cmenulib
Introduzione
La libreria ha due funzioni principali:
- sollevare dall'interfacciamento a Curses per i menu
- rendere l'utilizzo dei menu di facile approccio
- utilizzare nella creazione del codice una relazione
menuitem-funzione per mantenere il codice pulito
Caratteristiche Menu
I menu hanno le seguenti caratteristiche:
- gestione Menubar multiple
- gestione menu a tendina
- gestione mark/unmark ( grande invenzione )
- consentono movimenti mediante i tasti cursore
- gestione menu con finestra di scroll
Interfaccia programmatica
L'interfaccia programmatica DEVE essere semplice e possibilmente
portabile.
L'interfaccia alla gestione dei menu viene fatta mediante 4 funzioni
in totale, comprese quelle di inizializzazione e chiusura.
Le funzioni sono:
- MyMenuInit()
- mb_ctor()
- mb_choose()
- MyMenuFinish()
A parte la prima e l'ultime che sono intuitivamente le funzioni
di inizializzazione e chiusura dell'ambiente Curses per l'utilizzo
dei menu, le due centrali mb_ctor() e mb_choose() sono le uniche
di interfaccia vera e propria.
La funzione mb_ctor() e' in constructor (costruttore) del menu,
mentre la funzione mb_choose() e' il gestore.
La menubar, i menu e gli item di questi sono predisposti mediante
strutture di semplice formato.
Oggetti
Gli oggetti utilizzati dati menu sono:
Il livello di utilizzo degli stessi e' gerarchico, per cui avremo
una struttura tipica:
+---------+
| menubar |
+---------+
|
+------------------+----------------+----------
| | |
+------+ +------+ +------+
| menu | | menu | | menu | ...
+------+ +------+ +------+
| | |
| | |
+----+----+----+ +----+----+----+ +----+----+----+---+
|item|item|item| |item|item|item| |item|item|item|...|
+----+----+----+ +----+----+----+ +----+----+----+---+
Al primo livello compare solamente un oggetto di tipo menubar
che include al suo interno piu' oggetti di tipo menu, i quali
a loro volta includono piu' oggetti di tipo item.
Strutture Dati
Struttura MENUBAR
La struttura MENUBAR definisce le caratteristiche della menubar.
E' composta da tre campi:
- id .. e' un id non utilizzato
- nmenus .. numeroo dei menu presenti nella menubar
- menus .. puntatore ad un array di strutture che contengono
la descrizione dei menu
Se si utilizza una unica menubar (caso tipico) questa struttura
deve essere utilizzata una sola volta.
/*------------------------------------------------------------
* struttura per MenuBar
*----------------------------------------------------------*/
typedef struct {
int id; /* id della menubar */
int nmenus; /* numero dei menu presenti sulla menubar */
MENU *menus; /* array menu presenti sulla menubar */
} MENUBAR;
Struttura MENU
Per ciascun menu presente sulla menubar deve esistere una di
queste strutture.
E' composta di 5 campi:
- id .. user id del menu (utilizzato dall'utente)
- name .. nome del menu
- col .. colonna in cui viene posizionato il menu
- nItems .. numero di item associati a questo menu
- item .. puntatore ad un array di stutture che descrivono
gli item collegati a questo menu
/*------------------------------------------------------------
* struttura per ogni Menu associato alla MenuBar
*----------------------------------------------------------*/
typedef struct MENU {
int id; /* id del menu */
char *name; /* titolo del menu */
int col; /* colonna in cui viene presentato il menu */
int nItems; /* numero di item del menu */
ITEM *item; /* array degli item */
} MENU;
Struttura ITEM
Per ciascun item presente in un menu deve esistere una di
queste strutture.
E' composta di 6 campi:
- id .. user id del item (utilizzato dall'utente)
- name .. nome del item
- flag .. flag sulle opzioni del item (ITEM_MARK)
- help .. stringa di help associata al menu (NON IMPLEMENTATO)
- funmark .. funzione che viene chiamata al mark di un item
- fun .. funzione che viene chiamata alla selezione di un item
La struttura ITEM viene utilizzata anche per gli scrollmenu.
/*------------------------------------------------------------
* struttura per ogni Item (riga) di un menu
*----------------------------------------------------------*/
typedef struct {
int id; /* user id menu */
char *name; /* name of menu */
int flag; /* ITEM_ON, ITEM_MARK */
char *help; /* help string not implemented */
int (*funmark)( int menu,int item,int mark ); /* pfun mark */
int (*fun)( int menu, int item, int flag ); /* pfun select */
} ITEM;
Libreria libcmenu.a
Funzioni
Di seguito divise per tipologia le funzioni esistenti:
void CMenuInit()
void CMenuFinish()
void CMenuOption( int option, char * value )
int Mscroll( int orgy, int orgx, int id,
char *title, int maxrows, ITEM *array, int timeout )
int MakeMenuBar( int mb_id )
int AddMenusExp( int mb_id, int m_id, char *name, int col,
int (*fun)( int, int, int ), char *cmd )
int AddItemsExp( int mb_id, int nmenu, char *name, int flag, char *help,
int (*funmark)( int, int, int ),
int (*fun)( int, int, int ), char *cmd )
int ManageMenu( int m_id, char *title, int orgy, int orgx, int nrow )
int ManageMenuBar( int mb_id )
int CMenuCls()
int CMenuExecf( int waitchar, char *va_alist, ... )
int Messagef( int r, int c, int rlen, int clen, int to, char *va_alist, ... )
int MessageList( int r, int c, int nrow, int ncol, char **message, int nmess )
int Htmlf( int r, int c, int rlen, int clen, int to, char *va_alist, ... )
int Alert( int r, int c, int rlen, int clen, char *message )
int Dialogf( int r, int c, int rlen, int clen, char *out, char *va_alist, ... )
int Confirmf( int r, int c, int rlen, int clen, char *va_alist, ... )
char *MGetString( int r, int c, int rlen, int clen,
int max, char *out, char *va_alist, ... )
int MDialog( int r1, int c1, int rlen, int clen, char *title, int n, OBJ *obj )
int Radio( int r, int c, int rlen, int clen, char *title, int n, RADIO *args )
int CMenuSpread( char *buf )
int CMenuFire()
int CMenuHexEditFile( char *fname, int fedit )
int CMenuHexEditMemory( char *bufin, int address, int offset, int fedit )
int Mctor( MENUINT *this, int id, int y, int x, char *title, int maxr )
int Msort_byname( const void *f1, const void *f2 )
int Msort( MENUINT *this, int (*funsort)(const void*, const void*) )
Mset( int exit_with_enter )
MENUINT *Mgetcurrent( void )
void Mdtor( MENUINT *this )
void Mdrawall( MENUINT *this )
void Mdrawitems( MENUINT *this )
void Mdraw( MENUINT *this )
void Mrefresh( MENUINT *this )
void Mrefreshcurrent( void )
void Mclear( MENUINT *this )
void Mhelp( MENUINT *this, char *string )
void Mhelpclear( MENUINT *this )
int MscrollbarClear( MENUINT *this )
int Mscrollbar( MENUINT *this )
void Mhome( MENUINT *this, int redraw_flag )
void Mend( MENUINT *this, int redraw_flag )
void Mnextpg( MENUINT *this, int redraw_flag )
void Mnext( MENUINT *this, int redraw_flag )
void Mprevpg( MENUINT *this, int redraw_flag )
void Mprev( MENUINT *this, int redraw_flag )
int Mmark( MENUINT *this, int mark )
int Mmarkelement( int element, int mark, int redraw )
int Mmarkcurrent( int mark, int redraw )
int Mmarkall( int mark )
int Mexecfun( MENUINT *this )
int Mexeccmd( MENUINT *this )
int Mchoose( MENUINT *this )
int Miterate( int from, int to, int (*fun)( int index, char *str ) )
int Mprint( MENUINT *this )
MENU *MenuCreate( int id, char *name, int (*fun)(int,int,int), char *cmd )
int ItemAdd( MENU *pm, char *name, int flag, char *help,
int (*funmark)(int,int,int), int (*fun)(int,int,int), char *cmd )
int ItemAddS( MENU *pm, char *name, int flag, char *help,
int (*funmark)(int,int,int), int (*fun)(char*), char *cmd )
int MenuRun( MENU *pm, int orgy, int orgx, int nrow )
int MenuDelete( MENU *pm )
int ArrCtor( char *arr[], int row, int col, int nrow, int ncol,
char *title, BUTTONS *buttons, CONTROLS *controls )
int arr_ctor( char *arr[], int row, int col, int nrow, int ncol,
char *title, BUTTONS *buttons )
int getscrollmsize( char *title, int maxr, ITEM *arr,
int *rp, int *cp, int *scrollp, int nitem )
int calcpopyx( int rows, int cols, int cury,
int minx, int maxx, int *yp, int *xp)
int Mbuttondraw( WINDOW *w, int r, int c, BUTTONS *buttons, int from, int to )
int Mcontroldraw( WINDOW *w, int r, int c, CONTROLS *controls )
int Mbuttonchoose( MENUINT *this, int k )
int Mcontrolchoose( MENUINT *this, int k )
int MakeArrayFromFile( char *file, char *title,
int row, int col, int nrow,
BUTTONS *b, CONTROLS *c )
int MBctor( MENUBAR *this )
void MBrefresh()
void MBdraw( MENUBAR *this )
MBbuttons( int from )
void MBfirst( MENUBAR *this, int redraw_flag )
void MBlast( MENUBAR *this, int redraw_flag )
void MBnext( MENUBAR *this, int redraw_flag )
void MBprev( MENUBAR *this, int redraw_flag)
int MBexecfun( MENUBAR *this )
int MBchoose( MENUBAR *this )
int MBclear( MYMENUBAR *this )
int MBdtor( MENUBAR *this )
void CMenuDebug( char *va_alist, ... )
void CMenuTrace( int level, char *file, int line, char *va_alist, ... )
void CMenuExit( int exitcode, char *va_alist, ... )
char *CMenuCd( char *path )
char *CMenuDirUsr( char *path, BUTTONS *buttons )
char *CMenuDir( char *path )
void CMenuTest()
char *CMenuFind( char *path )
void CMenuExecBg( char *cmd )
WIN *CMenuWinCreate( int r, int c, int rlen, int clen )
WIN *CMenuWinBoxCreate( int r, int c, int rlen, int clen,
char *title, BUTTONS *buttons )
int CMenuWinBoxRefresh( WIN *w )
int CMenuWinBoxClear( WIN *w )
int CMenuWinBoxMvAddStr( WIN *w, int r, int c, char *str )
int CMenuWinBoxDelete( WIN *w )
int CMenuWinBoxButDraw( WIN *w, int from )
int CMenuWinBoxChoose( WIN *w )
int CMenuWinBoxButton( WIN *w, int k )
int CMenuMoreFile( char *filename )
int CMenuWinWaitEnter( WIN *w, char *string )
int CMenuWinMoreReset( WINDOW *w, int maxlines )
int CMenuWinMore( WINDOW *w, char *string )
Manuali funzioni
NAME
DESCRIPTION
Init the "C-Menu" for Curses.
Must be called before any other function of C-Menu.
RETURN VALUES
NAME
DESCRIPTION
Clean Cmenu environment. Release Curses.
RETURN VALUES
NAME
int MessageList( int r, int c, int rlen, int clen, char **message, int nmess )
DESCRIPTION
Print the argument message (NULL-terminated) in a window, message
is a array of string pointer. The number of strings present in message
is determined by nmess.
The window has geometric characteristics defined by r, c, rlen, clen.
Wait for a character by user.
RETURN VALUES
NAME
int mb_ctor( MENUBAR *this )
DESCRIPTION
RETURN VALUES
ERRORS
WARNINGS
BUGS
CALL
NAME
int mb_choose( MENUBAR *this )
DESCRIPTION
Manage the selction on menubar.
If selected a menu, active and manage it.
RETURN VALUES
NAME
int
pm_ctor( POPUP_MENU *this, int id, int y, int x, char *title, int maxr )
DESCRIPTION
RETURN VALUES
ERRORS
WARNINGS
BUGS
CALL
NAME
int Mscroll( int orgy, int orgx, int id,
char *title, int maxrows, ITEM *array, int timeout )
DESCRIPTION
Display a single menu at position orgy, orgx.
The parameter title is the printed on the top of menu, the integer
maxrows is the max number of rows displayed, if the number of item
in parameter array, is greather than maxrows, the menu is display
scroll into array items.
If timeout is greather than 0 is used as seconds of timeout, the
time count begin at start of this function without regard of
key pressed.
RETURN VALUES
return the current item of menu when pressed ESCAPE
-1 exit for timeout
WARNINGS
To exit from a scroll-menu must be type one ESCAPE character.
Do not use alarm() in your code, why internally used by Cmenu.
NAME
DESCRIPTION
RETURN VALUES
NAME
int CMenuExecf( int waitchar, char *va_alist, ... )
DESCRIPTION
Exec a command via system() call.
If waitchar wait for a user key.
RETURN VALUES
NAME
int Messagef( int r, int c, int rlen, int clen, int to, char *va_alist, ... )
DESCRIPTION
Print the argument message in va_alist (NULL-terminated) in a window.
The window has geometric characteristics defined by r, c, rlen, clen.
If to > 0 wait to seconds and exit
else wait for e character by user.
RETURN VALUES
NAME
int Htmlf( int r, int c, int rlen, int clen, int to, char *va_alist, ... )
DESCRIPTION
Print the argument message in va_alist (NULL-terminated) in a window.
The window has geometric characteristics defined by r, c, rlen, clen.
If to > 0 wait to seconds and exit
else wait for e character by user.
Interpreted simil-HTML tags are:
RETURN VALUES
NAME
int Alert( int r, int c, int rlen, int clen, char *message )
DESCRIPTION
Print the argument message (NULL-terminated) in a window.
The window has geometric characteristics defined by r, c, rlen, clen.
Wait for a character by user.
RETURN VALUES
NAME
int Dialogf( int r, int c, int rlen, int clen, char *out, char *va_alist, ... )
DESCRIPTION
Print the argument prompt (NULL-terminated) in a window.
The window has geometric characteristics defined by r, c, rlen, clen.
Wait for one string typed by user and returned in buffer.
RETURN VALUES
NAME
int MDialog( int r, int c, int rlen, int clen, char *title, int n, OBJ *obj )
DESCRIPTION
RETURN VALUES
NAME
DESCRIPTION
RETURN VALUES
ERRORS
WARNINGS
BUGS
CALL
NAME
DESCRIPTION
RETURN VALUES
ERRORS
WARNINGS
BUGS
CALL
Esempi
Esempio di programma C che sfrutta la libreria:
static ITEM i_primo[] = {
{ 1, "Primo1", 0, "", 0, fPrimo1 },
{ 2, "Primo2", 0, "", 0, fPrimo2 },
{ 0, 0, 0, 0, 0 }
};
static ITEM i_secondo[] = {
{ 1, "Secondo1", 0, "", 0, fSecondo1 },
{ 2, "Secondo2", 0, "", 0, fSecondo2 },
{ 0, 0, 0, 0, 0 }
};
static ITEM i_null[] = { 0, 0, 0, 0, 0 };
static MENU m_menubar[] = {
{ 1, "PRIMO", 0, 4, i_primo },
{ 2, "SECONDO", 0, 5, i_secondo },
{ 7, "", 0, 0, i_null },
};
static MENUBAR mb_demo = { 0, 3, m_menubar };
/* funzioni di gestione item qui... */
int fPrimo1( int menu, int item, int flag ) { /* ... */ }
int fPrimo2( int menu, int item, int flag ) { /* ... */ }
int fSecondo1( int menu, int item, int flag ) { /* ... */ }
int fSecondo2( int menu, int item, int flag ) { /* ... */ }
int main( int argc, char *argv[] )
{
MyMenuInit();
mb_ctor( &mb_demo );
mb_choose( &mb_demo );
MyMenuFinish();
}
Qui un esempio di menu con il linguaggio.
Files forniti
Saranno forniti i seguenti files:
- libmenu.a .. libreria gestione menu
- mymenu.h .. include per utilizzare i menu
- menus.c .. sorgente di demo
Porting
Sono disponibili i seguenti porting:
- Unix (tutte le versioni)
- MS-DOS
Glossario
Menubar
+-------------------------------------- menu
v
+-------+-------+-------+.......--+
| MENU1 | MENU2 | MENU3 | 9 | <------------ menubar
+-------+-------+-------+.......--+
| item1 |
| item2 | <-------------------------------- items
|*item3 |
+-------+
^
+----------------------------------------- mark
ScrollMenu
|-CIAO----------| <--------------------- title
|*General... ^ <--------+
|*Primo... | <--------|------------ items
|*Secondo... v <--------+------------- scrollmenu indicators
|---------------|
|---------------|
DOC 1
SCROLLMENU
==========
Un caso particolare di menu viene messo sotto il nome di scrollmenu.
Questo menu permette la gestione una finestra di selezione degli item
inferiore alla dimensione fisica del menu.
Ad esempio avendo i seguenti item:
"primo"
"secondo"
"terzo"
"quarto"
"quinto"
"sesto"
"settimo"
e selezionando una finestra attiva di tre item e scendendo con il
cursore potremo vedere:
"primo" "terzo" "quarto"
"secondo" ... "quarto" ... "quinto"
"terzo" "quinto" "settimo"
Digitando ESCAPE si esce dal menu e viene ritornato l'item
selezionato, digitando RETURN viene eseguita la funzione associata
all'item come succede nei menu.
La funzione di interfaccia con gli scrollmenu e' la seguente:
scrollmenuv( row, col, id, Title, win_size, array_items )
I campi hanno questo significato:
row .. linea a cui deve essere stampato il menu
col .. colonna a cui deve essere stampato il menu
id .. identificatore menu (non usato)
win_size .. altezza della window (numero item presentati)
row .. linea a cui deve essere stampato il menu