Console Framework Classes 20103 - OOP344

From CDOT Wiki
Revision as of 22:06, 15 November 2010 by Fardad (talk | contribs) (→‎Methods)
Jump to: navigation, search


OOP344 | Weekly Schedule | Student List | Teams | Project | Student Resources

The Frame work

under construction!!!!

Your objective at this stage is to create a framework of classes designed to interact with the user. This user interface framework then can be used in development of any interactive application.

please note that the class definitions here are minimum requirement for the framework and you are free to add any enhancements or features you find useful. Obviously it would be wise the discuss these enhancements with your professor to make sure they are feasible.


Depending on the section you are in, you may have different scope in number of the classes you create. please double check your professor's notes on the project before you begin.


It is highly recommended to develop the classes in the order they are stated here. At each stage a tester program is provided to help you test your development. Executables of the test programs are available on matrix to show you how it is supposed to run.


Start by creating mock-up classes (class declaration and definition with empty methods that only compiles and don't do anything) Each class MUST have its own header file to hold its declaration and "cpp" file to hold its implementation. To make sure you do not do circular includes follow these simple guidelines:

  • Add recompilation safeguards to all your header files.
  • Always use forward declaration if possible instead of including a class.
  • Use includes only in files in which the actual header file code is used. avoid "just in case" includes.



General Internal Header file

The general header file holds the common setting and definition between all classes in the frame work. 

#ifndef ___CONFW_H__
#define ___CONFW_H__

 #ifndef _CRT_SECURE_NO_DEPRECATE
 #define _CRT_SECURE_NO_DEPRECATE
 #endif
 #ifndef _CRT_SECURE_NO_WARNINGS
 #define _CRT_SECURE_NO_WARNINGS
 #endif
#include <string.h>

extern "C"{
 #include "iol.h"
};

#define FW_BORDER_CHARS  "/-\\|/-\\|"

#define FW_MAX_NO_FIELDS 100
#define FW_BUTTON_HIT 1
#define FW_MAX_LINE_CHARS  (1024u)

#define FW_REFRESH -2
#define FW_FULL_FRAME -1
#define FW_NO_REFRESH 0


enum MessageStatus{ClearMessage,SetMessage};


#ifdef NO_HELPFUNC
# undef NO_HELPFUNC
#endif
#define NO_HELPFUNC ((void(*)(MessageStatus, FWDialog&))(0))
#ifdef NO_VALDFUNC
# undef NO_VALDFUNC
#endif
#define NO_VALDFUNC ((bool(*)(const char*, FWDialog&))(0))

#endif

File Names

Use the following rules to create filenames for your class.

  • Each class MUST have its own header file and cpp file for implementation
  • Use the class name for the name of the file but make sure it is all lowercase.
    For example FWBorder class should have fwborder.h and fwborder.cpp files for its implemetation

Classes

These classes encapsulate all the functions written in IOL library in an Object Oriented method:

Hierarchy

FWBorder
 |
 |---FWDialog
 |
 |
 |---FWField
       |
       |-------- FWLabel
       |         |
       |         |-------FWCheck
       |         |-------FWMenuItem (Maybe?)
       |
       |-------- FWButton
       |
       |
       |-------- FWLineEdit
       |         |
       |         |-------FWValEdit
       |
       |-------- FWText
       |
       |-------- FWCheckList (Maybe?)
       |-------- FWMenu (Maybe?)

FWBorder

FWBorder is the base of all IO entities in our framework. It encapsulate a window or a container in witch IO Fields are to be placed and run. It encapsulates a border, cordinates and size.

Class Definition

class FWBorder {
  int _row;
  int _col;
  int _height;
  int _width;
  char _border[9];
  bool _visible;
  FWBorder* _container;

protected:
  int absRow()const;
  int absCol()const;
public:
  FWBorder(int Row=-1, int Col=-1, int Width=-1,int Height=-1,
    bool Visible = false, 
    const char* Border=FW_BORDER_CHARS,
    FWBorder* Container = (FWBorder*)0);

  virtual void draw(int refresh = FW_NO_REFRESH)const;
  virtual ~FWBorder();
  
  void visible(bool val);
  bool visible()const;

  void container(FWBorder* theContainer);
  FWBorder* container();

  bool fullscreen()const;

  void row(int val);
  int row()const;

  void col(int val);
  int col()const;

  void size(int width, int height);
  int height()const;
  int width()const;

};

Properties

int _row, holds the relative coordinate of top row of this border with respect to its container.
int _col, same as _row, but for _col.
int _height, height of the entity.
int _width, width of the entity.
char _border[9], characters used to draw the border:

_border[0], left top
_border[1], top side
_border[2], right top
_border[3], right side
_border[4], right bottom
_border[5], bottom side
_border[6], bottom left
_border[7], left side

bool _visible; Indicates if the border surrounding the entity is to be drawn or not.
FWBorder* _container; holds the container (another FWBorder) which has opened this one (owner or container of the current FWBorder). _container will be NULL if this FWBorder does not have a container, in which case, it will be full screen and no matter what the values of row, col, width and height are, FWBorder will be Full Screen (no border will be drawn)

Methods

Protected
  • int absRow()const;
    it returns the sum of row() of this border plus all the row()s of the _containters
  • int absCol()const;
    it returns the sum of col() of this border plus all the col()s of the _containters

These two methods return the absolute coordinates of the FWBorder instance. (the row an column with respect to left top corner of the screen). These tow functions are used to draw the border on the screen.

public
  FWBorder(int Row=0, int Col=0, int Width=0,int Height=0,
    bool Visible = false, 
    const char* Border=FW_BORDER_CHARS,
    FWBorder* Container = (FWBorder*)0);

Sets the corresponding attributes to the incoming values in the argument list. 

  void visible(bool val);  
  bool visible()const;

  void container(FWBorder* theContainer);
  FWBorder* container();

  void row(int val);
  int row()const;

  void col(int val);
  int col()const;

  void size(int width, int height);
  int height()const;
  int width()const;

These Methods, set and get the corresponding attributes of the class 

  bool fullscreen()const;

Returns true if _container is null or else, it returns false; 

  virtual ~FWBorder();

An empty virtual destructor. 

  virtual void draw(int refresh = FW_NO_REFRESH)const;

If _container is null then it just clears the screen and exits.
Otherwise:

  • If Refresh flag is set to FW_REFRESH, it will call the _container's draw, passing the same value as argument
  • If the _visible flag is true, it will draw a box at _row and _col, with size of _width and _height using the _border characters and fills it with spaces. Otherwise it will just draw a box using spaces at the same location and same size.

Border Tester

BorderTester.cpp

FWField

This is an abstract class that is the base of any IO Field entity on a Dialog Box. It holds essential common attributes of a Fields (which some are inherited from border) and enforces implementation of essential methods by it children through pure virtual methods.

Forward declaration of FWDialog is needed for this class; 

class FWField: public FWBorder{
protected:
  void* _data;
public:
  FWField(int Row = 0, int Col = 0, 
         int Width = 0, int Height =0,
         void* Data = (void*) 0, 
         bool Bordered = false,
         const char* Border=FW_BORDER_CHARS);
  ~FWField();
  virtual int edit() = 0;
  virtual bool editable() const = 0;
 
  
  virtual void set(const void* data) = 0;
  virtual void* data();

  void container(FWDialog* theOwner);
  FWDialog* container();
};


Attributes

  void* _data;

Will hold the address of any type of data a FWField can hold.

Methods

  FWField(int Row = 0, int Col = 0, 
         int Width = 0, int Height =0,
         void* Data = (void*) 0, 
         bool Bordered = false,
         const char* Border=FW_BORDER_CHARS);

Passes the corresponding attributes to it's parents constructor and then sets the _data attribute to the incoming Data argument. 

  ~FWField();

An empty destructor 

  virtual int edit() = 0;

Enforces the children to implement an edit() method 

  virtual bool editable() const = 0;

Enforces the children to implement an editable() method that returns true if the class is to edit data and false if the class is to only display data. 

  virtual void set(const void* data) = 0;

Enforces the children to implement a set() method to set the _data attribute to the data the class is to work with. 

  virtual void* data();

Returns _data; 

  void container(FWDialog* theOwner);

Sets the _container attribute of FWBorder to theowner argument. 


  FWDialog* container();

Casts the return value of FWBorder::containr() to a FWDialog* and returns it.

FWLabel

FWLabel is child of FWField (therefore inheriting FWBorder too) responsible to display a short character string on the display. This class is never editable 

 class  FWLabel: public FWField{
   int _length;
 public:
   FWLabel(const char *Str, int Row, int Col, 
     int Len = -1);
   FWLabel(int Row, int Col, int Len);
   ~FWLabel();
   void draw(int Refresh = FW_NO_REFRESH) const;
   int edit();
   bool editable()const;
   void set(const void* str);
 };

Attributes

   int _length;

Holds the Length of the display area needed by iol_display.

Methods

   FWLabel(const char *Str, int Row, int Col, 
     int Len = -1);
  • Passes corresponding arguments to its parent constructor
  • Sets _length to the Len attribute.
  • Allocates enough memory for the size of data (that is _lentgth or the length of the Str if _length is zero or negative) and sets _data to point to it.
  • Then it will copy the content of what Str is pointing. 
   FWLabel(int Row, int Col, int Len);
  • Passes corresponding arguments to its parent constructor
  • Sets _length to the Len attribute.
  • Allocates Len + 1 bytes and sets it to be an empty string and then sets _data to point to it.

This constructor is used when FWLabel is used for messaging and does not need initial value. 

   ~FWLabel();

Deallocates the memory pointed by _data; 

   void draw(int Refresh = FW_NO_REFRESH) const;

Ignores the Refresh argument and make a direct call to iol_display to display the _data at absRow() and absCol() upto _length characters. 

   int edit();

Since no editing is happening here, it just calls draw(); 

   bool editable()const;

Returns False. 

   void set(const void* str);

copies the string pointed by str upto _length characters to _data.

FWDialog

FWDialog is a collection of several FWField; it organizes and groups FWFields for user entry and interaction
The following definition is just a suggestion for how to implement this class. You can change it under with your professors confirmation to a better way if you like.

Class Definition

class FWDialog: public FWBorder{
  private:
  int _fnum;
  int _curidx;
  FWField* _fld[FW_MAX_NO_FIELDS];
  bool _dyn[FW_MAX_NO_FIELDS];
  bool _editable;
  public:
  FWDialog(FWBorder *Container = (FWBorder*)0,
           int Row = -1, int Col = -1, 
           int Width = -1, int Height = -1, 
           bool Borderd = false,
           const char* Border=FW_BORDER_CHARS);
  virtual ~FWDialog();
  void draw(int fn = FW_NO_REFRESH)const;
  int edit(int fn = FW_NO_REFRESH);


  int add(FWField* field, bool dynamic = true);
  int add(FWField& field, bool dynamic = false);
  FWDialog& operator<<(FWField* field);
  FWDialog& operator<<(FWField& field);


  bool editable();
  int fieldNum()const;
  int curIndex()const;


  FWField& operator[](unsigned int index);
  FWField& curField();
};


Attributes

  int _fnum;

Holds the number of FWFields added to FWDialog. 

  int _curidx;

Holds the index of the FWFields that is being edited now. 

  FWField* _fld[FW_MAX_NO_FIELDS];

An array of FWFields pointers. Initially all the elements of _fld is set to null. When a FWField is added to the form, it will be pointed by one of the elements of this array. 


  bool _dyn[FW_MAX_NO_FIELDS];

An array of boolean values exactly to the number of elements of _fld. When FWField number "n" is added to FWDialog and is pointed by _fld[n-1], the corresponding _dyn[n-1] indicate if the FWField held in _fld[n-1] is dynamically allocated or not. the _dyn flags will be used in the destructor as deallocation condition for each _fld element. 


  bool _editable;

Is set to true, if at least one of the FWFields in _fld is editable.

Methods

  FWDialog(FWBorder *Container = (FWBorder*)0,
           int Row = -1, int Col = -1, 
           int Width = -1, int Height = -1, 
           bool Borderd = false,
           const char* Border=FW_BORDER_CHARS);

Passes all the arguments to its parent constructor and then sets the FWDialog to an empty dialog.
(Sets all the Field pointers to null, flags to false and numbers to zero) 


  virtual ~FWDialog();

Loops through all the field pointers and checks to see if any of them are dynamically allocated and deletes them. (it only deletes those fields that are flagged as dynamic) 

  void draw(int fn = FW_NO_REFRESH)const;

If fn is FW_REFRESH of FW_FULL_FRAME, it will call its parent draw with fn as its argument. Then It will draw all the Fields in the Dialog.
If fn is FW_NO_REFRESH, then it will just draw all the Fields in the Dialog.
If fn is a non-zero positive value, then it will only draw Field number fn in the dialog. (First added Field is field number one.) 

  int edit(int fn = FW_NO_REFRESH);

If FWDialog is not editable (all fields are non-editable), it will just display the Dialog and then waits for the user to enter a key and then terminates the function returning the key.
If fn is 0 or less, then before editing, the draw method is called with fn as its argument and then editing begins from the first editable Field.

If fn is greater than 0 then editing begins from the first editable key on or after Field number fn.

Note that fn is the sequence number of field and not the index. (First field number is one)

Start editing from field number fn;

Call the edit of each field and depending on the value returned, do the following:

  1. For ENTER_KEY, TAB_KEY and DOWN_KEY, go to next editable Field , if this is the last editable Field then restart from Field number one.
  2. For UP_KEY go to the previous editable Field, if there is no previous editable Field, go to the last editable Field in the Dialog.
  3. For any other key, terminate the edit function returning the character which caused the termination.
  int add(FWField* field, bool dynamic = true);

Adds the FWField pointed by field to the Fields of the Dialog; by appending the value of the field pointer to the _fld array , setting the corresponding _dyn element to the value of dynamic argument and then increasing _fnum by one and returning it. 


  int add(FWField& field, bool dynamic = false);

Makes a direct call to the previous add() method, passing the address of the field argument and the value of the dynamic argument and returning what it returns. 

  FWDialog& operator<<(FWField* field);

Makes a direct call the first add() method returning a reference of the owner (the FWDialog); 

  FWDialog& operator<<(FWField& field);

Makes a direct call the second add() method returning a reference of the owner (the FWDialog); 

  bool editable();

If at least one editable field exist in the Dialog, it returns true, otherwise, it returns false; 


  int fieldNum()const;

Returns number of fields added to the Dialog. 


  int curIndex()const;

Returns the index of the Field that was just being edited. 

  FWField& operator[](unsigned int index);

Returns the reference of the Field with incoming index. (Note that here, the first field index is 0) 

  FWField& curField();

Returns the reference of the Field that was just being edited.

Dialog and Label Tester

Test2DialogAndLabel.cpp

FWLineEdit

Class Definition

class FWLineEdit: public FWField{
  bool _dyn;
  int _maxdatalen;
  int* _insertmode;
  int _curpos;
  int _offset;
public:
  FWLineEdit(char* Str, int Row, int Col, int Width,
    int Maxdatalen, int* Insertmode, 
    bool Bordered = false,
          const char* Border=FW_BORDER_CHARS);
  FWLineEdit(int Row, int Col, int Width,
    int Maxdatalen, int* Insertmode, 
    bool Bordered = false,
          const char* Border=FW_BORDER_CHARS);
  ~FWLineEdit();
  void draw(int Refresh = FW_NO_REFRESH)const;
 
  int edit();
  bool editable()const;

  void  set(const void* Str);
};
 
  FWLineEdit(char* Str, int Row, int Col, int Width,
    int Maxdatalen, int* Insertmode, 
    bool Bordered = false,
          const char* Border=FW_BORDER_CHARS);

LineEdit, sets the Field's _data to the value of str. If LineEdit is instantiated with this constructor then it will edit an external string provided by the caller function of LineEdit. LineEdit in this case is not creating any dynamic memory, therefore _dyn is set to false (therefore the destructor will not attempt to deallocate the memory pointed by _data).
The location (row and col) and Bordered are directly passed to the parent (FWField) and str is passed as data to the parent constructor. Unlike Label, LineEdit could have border or not so depending on this (Bordered being true or false) the Height is set to 3 or 1 respectfully.
(hint: use ? : operator to pass the proper value to FWField's constructor) 

  FWLineEdit(int Row, int Col, int Width,
    int Maxdatalen, int* Insertmode, 
    bool Bordered = false,
          const char* Border=FW_BORDER_CHARS);

Works exactly like the previous constructor with one difference; since no external data is passed to be edited here, this constructor must allocate enough dynamic memory to accommodate editing of Maxdatalen characters. Then make it an empty string and set Fields's _data to point to it. Make sure _dyn is set to true in this case, so the destructor knows that it has to deallocate the memory at the end. 

  ~FWLineEdit();

If _dyn is true, it will deallocate the character array pointed by Fields's _data 

void draw(int Refresh = FW_NO_REFRESH)const;

If the Border is visible, it will first call Border's draw passing Refreshas an argument to it.
Then it will make a direct call to iol_display to show the data kept in Field's _data.
The values used for the arguments of iol_display are:

  • str: address of string pointed by _data + the value of _offset
  • row: absRos() (add one if border is visible)
  • col: absCol() (add one if border is visible)
  • len: width() (reduce by two is border is visible')
int edit();

Makes and direct call to, and returns iol_edit(). For the coordinates and width arguments follow the same rules as the draw function. For the rest of the arguments of iol_edit, use the attributes of FWLineEdit. 

bool editable()const;

Always return true; 

void  set(const void* Str);

Copies the characters pointed by Str into the memory pointed by Field's _data up to _maxdatalen characters.

Dialog and Line editor Tester

DialogAndLineEditor.cpp

FWButton

Button is a child of FWField. It displays a small piece of text (usually one word or two) and accepts one key hit entry. When in edit mode, to indicate the editing mode, it will surround the text with squared brackets.

Class Definition

 class  FWButton: public FWField{
 public:
   FWButton(const char *Str, int Row, int Col, 
            bool Bordered = true,
            const char* Border=FW_BORDER_CHARS);
   ~FWButton();
   void draw(int Refresh = FW_NO_REFRESH) const;
   int edit();
   bool editable()const;
   void set(const void* str);
 };

Methods

FWButton(const char *Str, int Row, int Col, 
            bool Bordered = true,
            const char* Border=FW_BORDER_CHARS);

When creating a Button, allocate enough memory to hold the contents of the Str and set Field's _data to point to it. Then copy the content of Str into the newly allocated memory.
Pass all the arguments directly to Field's constructor.
For Field size (width and hight) do the following:
For width: Set width to the length of Str + 2 (adding 2 for surrounding brackets) or if the Button is bordered set width to the length of Str + 4 (adding 2 for surrounding brackets and 2 for the borders). For height: Set the height to 1 or if the Button is bordered, set the height to 3. 

~FWButton();

Deallocates the allocated memory pointed by Field's _data. 

void draw(int Refresh = FW_NO_REFRESH) const;
  • First calls Border's draw()

use iol_display to display the Button's text (pointed by Field's _data)

  • If not bordered
    display the text at absRow() and absCol()
  • If bordered
    display the text at absRow()+1 and absCol()+2
int edit();

First draw() the Button, then surround it by squared brackets, place the cursor under the first character of Button's text and wait for user entry.
When user hits a key, if the key is ENTER_KEY or SPACE, return FW_BUTTON_HIT (defined in confw.h) otherwise return the entered key.
Make sure the surrounding characters are replaced with spaces before exiting the edit() method. 

bool editable()const;

Always returns true; 

void set(const void* str);

Reallocate memory for new text set it to content of str:

First deallocated what is pointed by Field's _data.
Then allocate new memory to the size of content of str and copy the content into it and make Field's _data point to it.

Button Tester

ButtonTest.cpp

FWCHECK

FWCheck class is a flagged Label. FWCheck prints a checkbox and a Label in front of it and waits for user entry to possibly toggle the checkbox and exit.

Class Definition

class FWCheck : public FWLabel {
  int _flag;
  int _radio;
  char _format[4];
public:
  FWCheck(bool Checked,const char* Format, const char* Text, int Row, int Col, bool IsRadio = false);
  void draw(int Refresh = FW_NO_REFRESH) const;
  int edit();
  bool editable()const;
  void set(const void* flag);
  void *data();
};

Attributes

  int _flag;
  int _radio;
  char _format[4];
  • _flag holds the status of the Checkbox (0: unchecked or 1: checked).
  • _radio dictates the behavior of the Checkbox as a radio-button, or a check-mark.
  • _format holds the characters, the Checkbox is drawn with (i.e. "[X]", "(O)", "<*>", etc...).

Methods

  FWCheck(bool Checked,const char* Format, const char* Text, int Row, int Col, bool IsRadio = false);

  void draw(int Refresh = FW_NO_REFRESH) const;

  int edit();

  bool editable()const;

  void set(const void* flag);

  void *data();

Button Tester

CheckboxTester.cpp

FWValEdit

Class Definition

class FWValEdit: public FWLineEdit{
  void (*_help)(MessageStatus, FWDialog&);
  bool (*_validate)(const char*, FWDialog&);
public:
  FWValEdit(char* Str, int Row, int Col, int Width,
        int Maxdatalen, int* Insertmode,
        bool (*Validate)(const char* , FWDialog&) = NO_VALDFUNC, 
        void (*Help)(MessageStatus, FWDialog&) = NO_HELPFUNC,
        bool Bordered = false,
        const char* Border=FW_BORDER_CHARS);
  FWValEdit(int Row, int Col, int Width,
        int Maxdatalen, int* Insertmode,
        bool (*Validate)(const char* , FWDialog&) = NO_VALDFUNC, 
        void (*Help)(MessageStatus, FWDialog&) = NO_HELPFUNC,
        bool Bordered = false,
        const char* Border=FW_BORDER_CHARS);
  int edit();
};

Validated Line editor Tester

FWValEditTester.cpp

Retrieved from "https://wiki.cdot.senecapolytechnic.ca/w/index.php?title=Console_Framework_Classes_20103_-_OOP344&oldid=49755"