1 // * This makes emacs happy -*-Mode: C++;-*-
2 /****************************************************************************
3 * Copyright (c) 1998-2004,2005 Free Software Foundation, Inc. *
5 * Permission is hereby granted, free of charge, to any person obtaining a *
6 * copy of this software and associated documentation files (the *
7 * "Software"), to deal in the Software without restriction, including *
8 * without limitation the rights to use, copy, modify, merge, publish, *
9 * distribute, distribute with modifications, sublicense, and/or sell *
10 * copies of the Software, and to permit persons to whom the Software is *
11 * furnished to do so, subject to the following conditions: *
13 * The above copyright notice and this permission notice shall be included *
14 * in all copies or substantial portions of the Software. *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS *
17 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF *
18 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. *
19 * IN NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, *
20 * DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR *
21 * OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR *
22 * THE USE OR OTHER DEALINGS IN THE SOFTWARE. *
24 * Except as contained in this notice, the name(s) of the above copyright *
25 * holders shall not be used in advertising or otherwise to promote the *
26 * sale, use or other dealings in this Software without prior written *
28 ****************************************************************************/
30 /****************************************************************************
31 * Author: Juergen Pfeifer, 1997 *
32 ****************************************************************************/
34 // $Id: cursesf.h,v 1.28 2005/08/13 18:08:24 tom Exp $
36 #ifndef NCURSES_CURSESF_H_incl
37 #define NCURSES_CURSESF_H_incl 1
49 // -------------------------------------------------------------------------
50 // The abstract base class for buitin and user defined Fieldtypes.
51 // -------------------------------------------------------------------------
53 class NCURSES_IMPEXP NCursesFormField; // forward declaration
55 // Class to represent builtin field types as well as C++ written new
56 // fieldtypes (see classes UserDefineFieldType...
57 class NCURSES_IMPEXP NCursesFieldType
59 friend class NCursesFormField;
64 inline void OnError(int err) const THROWS(NCursesFormException) {
66 THROW(new NCursesFormException (err));
69 NCursesFieldType(FIELDTYPE *f) : fieldtype(f) {
72 virtual ~NCursesFieldType() {}
74 // Set the fields f fieldtype to this one.
75 virtual void set(NCursesFormField& f) = 0;
79 : fieldtype(STATIC_CAST(FIELDTYPE*)(0))
83 NCursesFieldType& operator=(const NCursesFieldType& rhs)
91 NCursesFieldType(const NCursesFieldType& rhs)
92 : fieldtype(rhs.fieldtype)
99 // -------------------------------------------------------------------------
100 // The class representing a forms field, wrapping the lowlevel FIELD struct
101 // -------------------------------------------------------------------------
103 class NCURSES_IMPEXP NCursesFormField
105 friend class NCursesForm;
108 FIELD *field; // lowlevel structure
109 NCursesFieldType* ftype; // Associated field type
112 inline void OnError (int err) const THROWS(NCursesFormException) {
114 THROW(new NCursesFormException (err));
118 // Create a 'Null' field. Can be used to delimit a field list
120 : field(STATIC_CAST(FIELD*)(0)),
121 ftype(STATIC_CAST(NCursesFieldType*)(0))
125 // Create a new field
126 NCursesFormField (int rows,
130 int offscreen_rows = 0,
131 int additional_buffers = 0)
133 ftype(STATIC_CAST(NCursesFieldType*)(0))
135 field = ::new_field(rows, ncols, first_row, first_col,
136 offscreen_rows, additional_buffers);
141 NCursesFormField& operator=(const NCursesFormField& rhs)
149 NCursesFormField(const NCursesFormField& rhs)
150 : field(rhs.field), ftype(rhs.ftype)
154 virtual ~NCursesFormField ();
156 // Duplicate the field at a new position
157 inline NCursesFormField* dup(int first_row, int first_col)
159 NCursesFormField* f = new NCursesFormField();
161 OnError(E_SYSTEM_ERROR);
164 f->field = ::dup_field(field,first_row,first_col);
171 // Link the field to a new location
172 inline NCursesFormField* link(int first_row, int first_col) {
173 NCursesFormField* f = new NCursesFormField();
175 OnError(E_SYSTEM_ERROR);
178 f->field = ::link_field(field,first_row,first_col);
185 // Get the lowlevel field representation
186 inline FIELD* get_field() const {
190 // Retrieve info about the field
191 inline void info(int& rows, int& ncols,
192 int& first_row, int& first_col,
193 int& offscreen_rows, int& additional_buffers) const {
194 OnError(::field_info(field, &rows, &ncols,
195 &first_row, &first_col,
196 &offscreen_rows, &additional_buffers));
199 // Retrieve info about the fields dynamic properties.
200 inline void dynamic_info(int& dynamic_rows, int& dynamic_cols,
201 int& max_growth) const {
202 OnError(::dynamic_field_info(field, &dynamic_rows, &dynamic_cols,
206 // For a dynamic field you may set the maximum growth limit.
207 // A zero means unlimited growth.
208 inline void set_maximum_growth(int growth = 0) {
209 OnError(::set_max_field(field,growth));
212 // Move the field to a new position
213 inline void move(int row, int col) {
214 OnError(::move_field(field,row,col));
217 // Mark the field to start a new page
218 inline void new_page(bool pageFlag = FALSE) {
219 OnError(::set_new_page(field,pageFlag));
222 // Retrieve whether or not the field starts a new page.
223 inline bool is_new_page() const {
224 return ::new_page(field);
227 // Set the justification for the field
228 inline void set_justification(int just) {
229 OnError(::set_field_just(field,just));
232 // Retrieve the fields justification
233 inline int justification() const {
234 return ::field_just(field);
236 // Set the foreground attribute for the field
237 inline void set_foreground(chtype foreground) {
238 OnError(::set_field_fore(field,foreground));
241 // Retrieve the fields foreground attribute
242 inline chtype fore() const {
243 return ::field_fore(field);
246 // Set the background attribute for the field
247 inline void set_background(chtype background) {
248 OnError(::set_field_back(field,background));
251 // Retrieve the fields background attribute
252 inline chtype back() const {
253 return ::field_back(field);
256 // Set the padding character for the field
257 inline void set_pad_character(int padding) {
258 OnError(::set_field_pad(field, padding));
261 // Retrieve the fields padding character
262 inline int pad() const {
263 return ::field_pad(field);
266 // Switch on the fields options
267 inline void options_on (Field_Options opts) {
268 OnError (::field_opts_on (field, opts));
271 // Switch off the fields options
272 inline void options_off (Field_Options opts) {
273 OnError (::field_opts_off (field, opts));
276 // Retrieve the fields options
277 inline Field_Options options () const {
278 return ::field_opts (field);
281 // Set the fields options
282 inline void set_options (Field_Options opts) {
283 OnError (::set_field_opts (field, opts));
286 // Mark the field as changed
287 inline void set_changed(bool changeFlag = TRUE) {
288 OnError(::set_field_status(field,changeFlag));
291 // Test whether or not the field is marked as changed
292 inline bool changed() const {
293 return ::field_status(field);
296 // Return the index of the field in the field array of a form
297 // or -1 if the field is not associated to a form
298 inline int (index)() const {
299 return ::field_index(field);
302 // Store a value in a fields buffer. The default buffer is nr. 0
303 inline void set_value(const char *val, int buffer = 0) {
304 OnError(::set_field_buffer(field,buffer,val));
307 // Retrieve the value of a fields buffer. The default buffer is nr. 0
308 inline char* value(int buffer = 0) const {
309 return ::field_buffer(field,buffer);
312 // Set the validation type of the field.
313 inline void set_fieldtype(NCursesFieldType& f) {
315 f.set(*this); // A good friend may do that...
318 // Retrieve the validation type of the field.
319 inline NCursesFieldType* fieldtype() const {
325 // This are the built-in hook functions in this C++ binding. In C++ we use
326 // virtual member functions (see below On_..._Init and On_..._Termination)
327 // to provide this functionality in an object oriented manner.
329 void _nc_xx_frm_init(FORM *);
330 void _nc_xx_frm_term(FORM *);
331 void _nc_xx_fld_init(FORM *);
332 void _nc_xx_fld_term(FORM *);
336 // -------------------------------------------------------------------------
337 // The class representing a form, wrapping the lowlevel FORM struct
338 // -------------------------------------------------------------------------
340 class NCURSES_IMPEXP NCursesForm : public NCursesPanel
343 FORM* form; // the lowlevel structure
346 NCursesWindow* sub; // the subwindow object
347 bool b_sub_owner; // is this our own subwindow?
348 bool b_framed; // has the form a border?
349 bool b_autoDelete; // Delete fields when deleting form?
351 NCursesFormField** my_fields; // The array of fields for this form
353 // This structure is used for the form's user data field to link the
354 // FORM* to the C++ object and to provide extra space for a user pointer.
356 void* m_user; // the pointer for the user's data
357 const NCursesForm* m_back; // backward pointer to C++ object
361 // Get the backward pointer to the C++ object from a FORM
362 static inline NCursesForm* getHook(const FORM *f) {
363 UserHook* hook = reinterpret_cast<UserHook*>(::form_userptr(f));
364 assert(hook != 0 && hook->m_owner==f);
365 return const_cast<NCursesForm*>(hook->m_back);
368 friend void _nc_xx_frm_init(FORM *);
369 friend void _nc_xx_frm_term(FORM *);
370 friend void _nc_xx_fld_init(FORM *);
371 friend void _nc_xx_fld_term(FORM *);
373 // Calculate FIELD* array for the menu
374 FIELD** mapFields(NCursesFormField* nfields[]);
378 inline void set_user(void *user) {
379 UserHook* uptr = reinterpret_cast<UserHook*>(::form_userptr (form));
380 assert (uptr != 0 && uptr->m_back==this && uptr->m_owner==form);
384 inline void *get_user() {
385 UserHook* uptr = reinterpret_cast<UserHook*>(::form_userptr (form));
386 assert (uptr != 0 && uptr->m_back==this && uptr->m_owner==form);
390 void InitForm (NCursesFormField* Fields[],
392 bool autoDeleteFields);
394 inline void OnError (int err) const THROWS(NCursesFormException) {
396 THROW(new NCursesFormException (err));
399 // this wraps the form_driver call.
400 virtual int driver (int c) ;
402 // 'Internal' constructor, builds an object without association to a
404 NCursesForm( int nlines,
408 : NCursesPanel(nlines, ncols, begin_y, begin_x),
409 form (STATIC_CAST(FORM*)(0)),
419 // Create form for the default panel.
420 NCursesForm (NCursesFormField* Fields[],
421 bool with_frame=FALSE, // reserve space for a frame?
422 bool autoDelete_Fields=FALSE) // do automatic cleanup?
431 InitForm(Fields, with_frame, autoDelete_Fields);
434 // Create a form in a panel with the given position and size.
435 NCursesForm (NCursesFormField* Fields[],
440 bool with_frame=FALSE, // reserve space for a frame?
441 bool autoDelete_Fields=FALSE) // do automatic cleanup?
442 : NCursesPanel(nlines, ncols, begin_y, begin_x),
450 InitForm(Fields, with_frame, autoDelete_Fields);
453 NCursesForm& operator=(const NCursesForm& rhs)
457 NCursesPanel::operator=(rhs);
462 NCursesForm(const NCursesForm& rhs)
466 b_sub_owner(rhs.b_sub_owner),
467 b_framed(rhs.b_framed),
468 b_autoDelete(rhs.b_autoDelete),
469 my_fields(rhs.my_fields)
473 virtual ~NCursesForm();
475 // Set the default attributes for the form
476 virtual void setDefaultAttributes();
478 // Retrieve current field of the form.
479 inline NCursesFormField* current_field() const {
480 return my_fields[::field_index(::current_field(form))];
483 // Set the forms subwindow
484 void setSubWindow(NCursesWindow& sub);
486 // Set these fields for the form
487 inline void setFields(NCursesFormField* Fields[]) {
488 OnError(::set_form_fields(form,mapFields(Fields)));
491 // Remove the form from the screen
492 inline void unpost (void) {
493 OnError (::unpost_form (form));
496 // Post the form to the screen if flag is true, unpost it otherwise
497 inline void post(bool flag = TRUE) {
498 OnError (flag ? ::post_form(form) : ::unpost_form (form));
502 inline void frame(const char *title=NULL, const char* btitle=NULL) {
504 NCursesPanel::frame(title,btitle);
506 OnError(E_SYSTEM_ERROR);
509 inline void boldframe(const char *title=NULL, const char* btitle=NULL) {
511 NCursesPanel::boldframe(title,btitle);
513 OnError(E_SYSTEM_ERROR);
516 inline void label(const char *topLabel, const char *bottomLabel) {
518 NCursesPanel::label(topLabel,bottomLabel);
520 OnError(E_SYSTEM_ERROR);
527 // Called after the form gets repositioned in its window.
528 // This is especially true if the form is posted.
529 virtual void On_Form_Init();
531 // Called before the form gets repositioned in its window.
532 // This is especially true if the form is unposted.
533 virtual void On_Form_Termination();
535 // Called after the field became the current field
536 virtual void On_Field_Init(NCursesFormField& field);
538 // Called before this field is left as current field.
539 virtual void On_Field_Termination(NCursesFormField& field);
541 // Calculate required window size for the form.
542 void scale(int& rows, int& ncols) const {
543 OnError(::scale_form(form,&rows,&ncols));
546 // Retrieve number of fields in the form.
548 return ::field_count(form);
551 // Make the page the current page of the form.
552 void set_page(int pageNum) {
553 OnError(::set_form_page(form, pageNum));
556 // Retrieve current page number
558 return ::form_page(form);
561 // Switch on the forms options
562 inline void options_on (Form_Options opts) {
563 OnError (::form_opts_on (form, opts));
566 // Switch off the forms options
567 inline void options_off (Form_Options opts) {
568 OnError (::form_opts_off (form, opts));
571 // Retrieve the forms options
572 inline Form_Options options () const {
573 return ::form_opts (form);
576 // Set the forms options
577 inline void set_options (Form_Options opts) {
578 OnError (::set_form_opts (form, opts));
581 // Are there more data in the current field after the data shown
582 inline bool data_ahead() const {
583 return ::data_ahead(form);
586 // Are there more data in the current field before the data shown
587 inline bool data_behind() const {
588 return ::data_behind(form);
591 // Position the cursor to the current field
592 inline void position_cursor () {
593 OnError (::pos_form_cursor (form));
595 // Set the current field
596 inline void set_current(NCursesFormField& F) {
597 OnError (::set_current_field(form, F.field));
600 // Provide a default key virtualization. Translate the keyboard
601 // code c into a form request code.
602 // The default implementation provides a hopefully straightforward
603 // mapping for the most common keystrokes and form requests.
604 virtual int virtualize(int c);
607 inline NCursesFormField* operator[](int i) const {
608 if ( (i < 0) || (i >= ::field_count (form)) )
609 OnError (E_BAD_ARGUMENT);
613 // Perform the menu's operation
614 // Return the field where you left the form.
615 virtual NCursesFormField* operator()(void);
617 // Exception handlers. The default is a Beep.
618 virtual void On_Request_Denied(int c) const;
619 virtual void On_Invalid_Field(int c) const;
620 virtual void On_Unknown_Command(int c) const;
625 // -------------------------------------------------------------------------
626 // This is the typical C++ typesafe way to allow to attach
627 // user data to a field of a form. Its assumed that the user
628 // data belongs to some class T. Use T as template argument
629 // to create a UserField.
630 // -------------------------------------------------------------------------
631 template<class T> class NCURSES_IMPEXP NCursesUserField : public NCursesFormField
634 NCursesUserField (int rows,
638 const T* p_UserData = STATIC_CAST(T*)(0),
639 int offscreen_rows = 0,
640 int additional_buffers = 0)
641 : NCursesFormField (rows, ncols,
642 first_row, first_col,
643 offscreen_rows, additional_buffers) {
645 OnError(::set_field_userptr(field, STATIC_CAST(void *)(p_UserData)));
648 virtual ~NCursesUserField() {};
650 inline const T* UserData (void) const {
651 return reinterpret_cast<const T*>(::field_userptr (field));
654 inline virtual void setUserData(const T* p_UserData) {
656 OnError (::set_field_userptr (field, STATIC_CAST(void *)(p_UserData)));
660 // -------------------------------------------------------------------------
661 // The same mechanism is used to attach user data to a form
662 // -------------------------------------------------------------------------
664 template<class T> class NCURSES_IMPEXP NCursesUserForm : public NCursesForm
667 // 'Internal' constructor, builds an object without association to a
669 NCursesUserForm( int nlines,
673 const T* p_UserData = STATIC_CAST(T*)(0))
674 : NCursesForm(nlines,ncols,begin_y,begin_x) {
676 set_user (const_cast<void *>(p_UserData));
680 NCursesUserForm (NCursesFormField Fields[],
681 const T* p_UserData = STATIC_CAST(T*)(0),
682 bool with_frame=FALSE,
683 bool autoDelete_Fields=FALSE)
684 : NCursesForm (Fields, with_frame, autoDelete_Fields) {
686 set_user (const_cast<void *>(p_UserData));
689 NCursesUserForm (NCursesFormField Fields[],
694 const T* p_UserData = STATIC_CAST(T*)(0),
695 bool with_frame=FALSE,
696 bool autoDelete_Fields=FALSE)
697 : NCursesForm (Fields, nlines, ncols, begin_y, begin_x,
698 with_frame, autoDelete_Fields) {
700 set_user (const_cast<void *>(p_UserData));
703 virtual ~NCursesUserForm() {
706 inline T* UserData (void) const {
707 return reinterpret_cast<T*>(get_user ());
710 inline virtual void setUserData (const T* p_UserData) {
712 set_user (const_cast<void *>(p_UserData));
717 // -------------------------------------------------------------------------
718 // Builtin Fieldtypes
719 // -------------------------------------------------------------------------
721 class NCURSES_IMPEXP Alpha_Field : public NCursesFieldType
726 void set(NCursesFormField& f) {
727 OnError(::set_field_type(f.get_field(),fieldtype,min_field_width));
731 Alpha_Field(int width)
732 : NCursesFieldType(TYPE_ALPHA),
733 min_field_width(width) {
737 class NCURSES_IMPEXP Alphanumeric_Field : public NCursesFieldType
742 void set(NCursesFormField& f) {
743 OnError(::set_field_type(f.get_field(),fieldtype,min_field_width));
747 Alphanumeric_Field(int width)
748 : NCursesFieldType(TYPE_ALNUM),
749 min_field_width(width) {
753 class NCURSES_IMPEXP Integer_Field : public NCursesFieldType
757 long lower_limit, upper_limit;
759 void set(NCursesFormField& f) {
760 OnError(::set_field_type(f.get_field(),fieldtype,
761 precision,lower_limit,upper_limit));
765 Integer_Field(int prec, long low=0L, long high=0L)
766 : NCursesFieldType(TYPE_INTEGER),
767 precision(prec), lower_limit(low), upper_limit(high) {
771 class NCURSES_IMPEXP Numeric_Field : public NCursesFieldType
775 double lower_limit, upper_limit;
777 void set(NCursesFormField& f) {
778 OnError(::set_field_type(f.get_field(),fieldtype,
779 precision,lower_limit,upper_limit));
783 Numeric_Field(int prec, double low=0.0, double high=0.0)
784 : NCursesFieldType(TYPE_NUMERIC),
785 precision(prec), lower_limit(low), upper_limit(high) {
789 class NCURSES_IMPEXP Regular_Expression_Field : public NCursesFieldType
794 void set(NCursesFormField& f) {
795 OnError(::set_field_type(f.get_field(),fieldtype,regex));
798 void copy_regex(const char *source)
800 regex = new char[1 + ::strlen(source)];
801 (::strcpy)(regex, source);
805 Regular_Expression_Field(const char *expr)
806 : NCursesFieldType(TYPE_REGEXP),
812 Regular_Expression_Field& operator=(const Regular_Expression_Field& rhs)
816 copy_regex(rhs.regex);
817 NCursesFieldType::operator=(rhs);
822 Regular_Expression_Field(const Regular_Expression_Field& rhs)
823 : NCursesFieldType(rhs),
826 copy_regex(rhs.regex);
829 ~Regular_Expression_Field() {
834 class NCURSES_IMPEXP Enumeration_Field : public NCursesFieldType
839 int non_unique_matches;
841 void set(NCursesFormField& f) {
842 OnError(::set_field_type(f.get_field(),fieldtype,
843 list,case_sensitive,non_unique_matches));
846 Enumeration_Field(const char* enums[],
847 bool case_sens=FALSE,
848 bool non_unique=FALSE)
849 : NCursesFieldType(TYPE_ENUM),
851 case_sensitive(case_sens ? -1 : 0),
852 non_unique_matches(non_unique ? -1 : 0) {
855 Enumeration_Field& operator=(const Enumeration_Field& rhs)
859 NCursesFieldType::operator=(rhs);
864 Enumeration_Field(const Enumeration_Field& rhs)
865 : NCursesFieldType(rhs),
867 case_sensitive(rhs.case_sensitive),
868 non_unique_matches(rhs.non_unique_matches)
873 class NCURSES_IMPEXP IPV4_Address_Field : public NCursesFieldType
876 void set(NCursesFormField& f) {
877 OnError(::set_field_type(f.get_field(),fieldtype));
881 IPV4_Address_Field() : NCursesFieldType(TYPE_IPV4) {
886 bool _nc_xx_fld_fcheck(FIELD *, const void*);
887 bool _nc_xx_fld_ccheck(int c, const void *);
888 void* _nc_xx_fld_makearg(va_list*);
892 // -------------------------------------------------------------------------
893 // Abstract base class for User-Defined Fieldtypes
894 // -------------------------------------------------------------------------
896 class NCURSES_IMPEXP UserDefinedFieldType : public NCursesFieldType
898 friend class UDF_Init; // Internal helper to set up statics
900 // For all C++ defined fieldtypes we need only one generic lowlevel
901 // FIELDTYPE* element.
902 static FIELDTYPE* generic_fieldtype;
905 // This are the functions required by the low level libforms functions
906 // to construct a fieldtype.
907 friend bool _nc_xx_fld_fcheck(FIELD *, const void*);
908 friend bool _nc_xx_fld_ccheck(int c, const void *);
909 friend void* _nc_xx_fld_makearg(va_list*);
911 void set(NCursesFormField& f) {
912 OnError(::set_field_type(f.get_field(),fieldtype,&f));
916 // Redefine this function to do a field validation. The argument
917 // is a reference to the field you should validate.
918 virtual bool field_check(NCursesFormField& f) = 0;
920 // Redefine this function to do a character validation. The argument
921 // is the character to be validated.
922 virtual bool char_check (int c) = 0;
925 UserDefinedFieldType() : NCursesFieldType(generic_fieldtype) {
930 bool _nc_xx_next_choice(FIELD*, const void *);
931 bool _nc_xx_prev_choice(FIELD*, const void *);
935 // -------------------------------------------------------------------------
936 // Abstract base class for User-Defined Fieldtypes with Choice functions
937 // -------------------------------------------------------------------------
939 class NCURSES_IMPEXP UserDefinedFieldType_With_Choice : public UserDefinedFieldType
941 friend class UDF_Init; // Internal helper to set up statics
943 // For all C++ defined fieldtypes with choice functions we need only one
944 // generic lowlevel FIELDTYPE* element.
945 static FIELDTYPE* generic_fieldtype_with_choice;
947 // This are the functions required by the low level libforms functions
948 // to construct a fieldtype with choice functions.
949 friend bool _nc_xx_next_choice(FIELD*, const void *);
950 friend bool _nc_xx_prev_choice(FIELD*, const void *);
953 // Redefine this function to do the retrieval of the next choice value.
954 // The argument is a reference to the field tobe examined.
955 virtual bool next (NCursesFormField& f) = 0;
957 // Redefine this function to do the retrieval of the previous choice value.
958 // The argument is a reference to the field tobe examined.
959 virtual bool previous(NCursesFormField& f) = 0;
962 UserDefinedFieldType_With_Choice() {
963 fieldtype = generic_fieldtype_with_choice;
967 #endif /* NCURSES_CURSESF_H_incl */