View source for Console Framework Classes 20103 - OOP344

=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.
<big><syntaxhighlight lang="cpp">
#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
</syntaxhighlight></big>
=File Names=
use the following rule 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==
<big><pre>
FWBorder
 |
 |---FWDialog
 |
 |
 |---FWField
       |
       |-------- IOLabel
       |         |
       |         |-------FWCheck
       |         |-------FWMenuItem (Maybe?)
       |
       |-------- FWButton
       |
       |
       |-------- FWLineEdit
       |         |
       |         |-------FWValEdit
       |
       |-------- FWText
       |
       |-------- FWCheckList (Maybe?)
       |-------- FWMenu (Maybe?)
</pre></big>
==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===
<big><syntaxhighlight lang="cpp">
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 height, int width);
  int height()const;
  int width()const;
};

</syntaxhighlight></big>
====Properties====
int _row, holds the relative coordinate of top row of this border with respect to its container.<br />
int _col, same as _row, but for _col. <br />
int _height, height of the entity. <br />
int _width, width of the entity. <br />
char _border[9], characters used to draw the border: <br />
: _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. <br />
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 '''_containter'''s
*int absCol()const;
*:it returns the sum of '''col()''' of this border plus all the '''col()'''s of the '''_containter'''s

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=====
<big><pre>
  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);
</pre></big>
Sets the corresponding attributes to the incoming values in the argument list.

<big><pre>
  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 height, int width);
  int height()const;
  int width()const;
</pre></big>

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

<big><pre>
  bool fullscreen()const;
</pre></big>
Returns true if _container is null or else, it returns false;

<big><pre>
  virtual ~FWBorder();
</pre></big>
An empty virtual destructor.

<big><pre>
  virtual void draw(int refresh = FW_NO_REFRESH)const;
</pre></big>

If _container is null then it just clears the screen and exits. <br />
Otherwise:<br />
*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===

[[OOP344 20103 BorderTester | 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;
 
<big><syntaxhighlight lang="cpp">
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();
};
</syntaxhighlight></big>



===Attributes===
<big><pre>
  void* _data;
</pre></big>
Will hold the address of any type of data a FWField can hold. 
===Methods===
<big><pre>
  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);
</pre></big>

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

<big><pre>
  ~FWField();
</pre></big>
An empty destructor

<big><pre>
  virtual int edit() = 0;
</pre></big>
Enforces the children to implement an edit() method

<big><pre>
  virtual bool editable() const = 0;
</pre></big>
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.
 
<big><pre>
  virtual void set(const void* data) = 0;
</pre></big>
Enforces the children to implement a set() method to set the _data attribute to the data the class is to work with.

<big><pre>
  virtual void* data();
</pre></big>
Returns _data;

<big><pre>
  void container(FWDialog* theOwner);
</pre></big>

Sets the _container attribute of FWBorder to '''theowner''' argument. 


<big><pre>
  FWDialog* container();
</pre></big>

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
<big><syntaxhighlight lang="cpp">
 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);
 };

</syntaxhighlight></big>

===Attributes===
<big><pre>
   int _length;
</pre></big>
Holds the Length of the display area needed by iol_display.

===Methods===
<big><pre>
   FWLabel(const char *Str, int Row, int Col, 
     int Len = -1);
</pre></big>
*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. 

<big><pre>
   FWLabel(int Row, int Col, int Len);
</pre></big>
*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. 

<big><pre>
   ~FWLabel();
</pre></big>
Deallocates the memory pointed by _data;
<big><pre>
   void draw(int Refresh = FW_NO_REFRESH) const;
</pre></big>
Ignores the Refresh argument and make a direct call to '''iol_display''' to display the _data at '''absRow()''' and '''absCol()''' upto '''_length''' characters.
<big><pre>
   int edit();
</pre></big>
Since no editing is happening here, it just calls draw();
<big><pre>
   bool editable()const;
</pre></big>
Returns False.
<big><pre>
   void set(const void* str);
</pre></big>
copies the string pointed by '''str''' upto '''_length''' characters to '''_data'''.

==FWDialog==
===Class Definition===
<big><syntaxhighlight lang="cpp">

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();
};


</syntaxhighlight></big>
===Dialog and Label Tester===
[[OOP344 20103 Framework Dialog and Label Tester | Test2DialogAndLabel.cpp]]

==FWLineEdit==

===Class Definition===
<big><syntaxhighlight lang="cpp">

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);
};

</syntaxhighlight></big>
=== Dialog and Line editor Tester ===

[[oop344 20103 Framework Dialog and Lineeditor Tester | DialogAndLineEditor.cpp]]

==FWButton==
===Class Definition===
<big><syntaxhighlight lang="cpp">

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

</syntaxhighlight></big>
===Button Tester===

[[Project Button Text - OOP344 20103 | ButtonTest.cpp]]

==FWCHECK==
===Class Definition===
<big><syntaxhighlight lang="cpp">
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();
};
</syntaxhighlight></big>

===Button Tester===
[[Framework Checkbox Tester - OOP344 21013 | CheckboxTester.cpp]]

==FWValEdit==
===Class Definition===
<big><syntaxhighlight lang="cpp">
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();
};
</syntaxhighlight></big>

===Validated Line editor Tester===
[[Validated LineEdit Tester - OOP344 20103 | FWValEditTester.cpp]]