Console UI Core Classes - OOP344 20112

From CDOT Wiki
Revision as of 11:34, 27 July 2011 by Fardad (talk | contribs)
Jump to: navigation, search


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


Objective

Your objective at this stage is to create series of core classes designed to interact with the user. These Core Classes then can be used in development of any interactive application.

Please note that the class definitions here are minimum requirement for the Core Classes and you are free to add any enhancements or features you find useful. However make sure that you discuss these enhancements with your professor to make sure they are feasible before implementation.

It is highly recommended to develop the classes in the order they are stated here. You must create your own tester programs for each class (if possible); However, close to due date of each release, a tester program is provided to help you verify the functionality of your classes. 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 header-file.
  • Use includes only in files in which the actual header file code is used.
  • Avoid "just in case" includes.

Due Dates

Adding Buffering logic to your iol logic (Release 0.1)

  • Duedate: Sunday Jul 24th, 23:59;

Before anything, go to YourRepository/branches/fardad/io_additions_changes and open iol.h and iol.c.

  1. Replace your iol.h content with mine (if you have any custom additions to your iol.h that mine does not cover it, add your custom prototypes and definitions. (note that my iol.h covers 4 platforms [compiler/operating systems]).
  2. Add the memory buffering logic that prevents flickering (the first 74 lines of code) to the top of your iol.c logic; (getBufChar,setBufChar, putMemch, scrbuf, curRow, curCol, bufrows, bufcols, alocScrBufMem, clrMemScr, freeScrBufMem, iol_capture, iol_restore, iol_getCurPos, iol_freeCapture)
  3. Replace your platform dependent logic with mine ( line 76 to 304) that are:
    1. iol_init
    2. iol_end
    3. iol_rows
    4. iol_cols
    5. iol_clrscr
    6. iol_flush
    7. iol_getch
    8. iol_movecur
    9. iol_putch
    10. iol_prnstr
  4. Compile the new additions with your iolmain.c, everything should work like before.
Instead of replacing the whole logic, you could modify your functions with my additions, but since you have only two platforms covered in your logic, It may be easier to just replace your platform dependent logic with mine.

Adding CFrame and CField classes to your project (Release 0.2)

  • Duedate: Sunday Jul 31th, 23:59;
  1. each team member:
    1. Branch the trunk into your branches (under whatever name you see fit)
    2. Get iolgh.h, cframe and cfield (.cpp and .h) and Test1Frame.cpp from svn://zenit.senecac.on.ca/oop344/trunk/Project and add it to your new branch and make sure it compiles and runs
    3. commit your new branch back to repository
  2. Only one of the team members
    Merge the new branch back to trunk and make sure it compiles and runs properly
DO NOT FORGET TO COMMENT EVERY AND EACH ACTION TAKEN ON THE REPOSITORY!!!!

Testers

CFrame

Tester program for CFrame Class: Test1Frame.cpp

IOL General Header file (iolgh.h)

The general header file holds the common setting and definition between all the Core Classes.

#ifndef ___IOLGH_H__
#define ___IOLGH_H__
 
#ifndef _CRT_SECURE_NO_DEPRECATE
#define _CRT_SECURE_NO_DEPRECATE
#endif
#ifndef _CRT_SECURE_NO_WARNINGS
#define _CRT_SECURE_NO_WARNINGS
#endif
 
#define C_MAX_NO_FIELDS 100
#define C_BUTTON_HIT 1
#define C_MAX_LINE_CHARS  (1024u)

//#define C_REFRESH -2
#define C_FULL_FRAME -1
#define C_NO_FRAME 0

#define C_BORDER_CHARS  "/-\\|/-\\|"
enum CDirection {iol_centre, iol_left, iol_right, iol_up, iol_down};

extern "C"{
#include "iol.h"
};
/* will be used later
enum MessageStatus{ClearMessage,SetMessage};


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


#define C_MAX_LINE_CHARS  (1024u)
#define C_INITIAL_NUM_OF_LINES (100u)
*/
#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 CFrame class should have cframe.h and cframe.cpp files for its implementation.

Hierarchy

CFrame
 |
 |---CDialog
 |
 |
 |---CField
       |
       |-------- CLabel
       |
       |
       |-------- CButton
       |
       |
       |-------- CLineEdit
       |         |
       |         |-------CValEdit
       |
       |-------- CText ?? maybe
       |
       |
       |-------- CCheck
       |
       |
       |-------- CCheckList ?? maybe
       |
       |
       |-------- CMenuItem  ?? maybe
       |
       |
       |-------- CMenu ?? maybe

Basic IOL Encapsulating Classes

CFrame

The code for this class is provided. You must understand and use it to develop your core classes.

CFrame class is responsible to create a frame or structure in which all user interface classes contain themselves in. It can draw a border around it self or be border-less. CFrame also, before displaying itself on the screen, will save the area it is about to cover, so it can redisplay them to hide itself.

CFrame is base of all objects in our user interface system.

#pragma once
#include "cgh.h"

class CFrame{
  int _row;      // relative row of left top corner to the container frame or the screen if _frame is null
  int _col;      // relative col of left top corner to the container frame or the screen if _frame is null
  int _height;   
  int _width;
  char _border[9];  // border characters
  bool _visible;    // is bordered or not
  CFrame* _frame;   // pointer to the container of the frame (the frame, surrounding this frame)
  char* _covered;   // pointer to the characters of the screen which are covered by this frame, when displayed
  void capture();   // captures and saves the characters in the area covered by this frame when displayed and sets 
                    // _covered to point to it
protected:
  int absRow()const;    
  int absCol()const;    
public:
  CFrame(int Row=-1, int Col=-1, int Width=-1,int Height=-1,
    bool Visible = false,
    const char* Border=C_BORDER_CHARS,
    CFrame* Frame = (CFrame*)0);
  
  virtual void draw(int fn=C_FULL_FRAME);
  virtual void move(CDirection dir);
  virtual void hide();

  virtual ~CFrame();
  
  /* setters and getters: */

  bool fullscreen()const;

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

  void frame(CFrame* theContainer);
  CFrame* frame();
  
  void row(int val);
  int row()const;

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

  void height(int val);
  int height()const;

  void width(int val);
  int width()const;

  void refresh();
};

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.
CFrame* _frame; holds the container (another CFrame) which has opened this one (owner or container of the current CFrame). _frame will be NULL if this CFrame 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, CFrame will be Full Screen (no border will be drawn)
char* _covered; is a pointer to a character array that hold what was under this frame before being drawn. When the CFrame wants to hide itself, it simple copies the content of this array back on the screen on its own coordinates.

Methods and Constructors

Private Methods

void capture();
if _covered pointer is not pointing to any allocated memory, it will call the bio_capture function to capture the area that is going to be covered by this frame and keeps its address in _covered.

Protected Methods

  • int absRow()const; calculates the absolute row (relative to the left top corner of the screen) and returns it.
    it returns the sum of row() of this border plus all the row()s of the _frames
  • int absCol()const; calculates the absolute column(relative to the left top corner of the screen) and returns it.
    it returns the sum of col() of this border plus all the col()s of the _frames

Public Methods

  CFrame(int Row=-1, int Col=-1, int Width=-1,int Height=-1,
    bool Visible = false,
    const char* Border=C_BORDER_CHARS,
    CFrame* Frame = (CFrame*)0);
Sets the corresponding attributes to the incoming values in the argument list and set _covered to null
  virtual void draw(int fn=C_FULL_FRAME);
  • First it will capture() the coordinates it is supposed to cover
  • If frame is fullscreen() then it just clears the screen and exits.

Otherwise:

  • 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.


  virtual void move(CDirection dir);

First it will hide the Frame, then adjust the row and col to more to the "dir" direction and then draws the Frame back on screen.

  virtual void hide();

using bio_restore()it restores the characters behind the Frame back on screen. It will also free the memory pointed by _covered;

  virtual ~CFrame();

It will make sure allocated memories are freed.

  bool fullscreen()const;
  void visible(bool val);
  bool visible()const;
  void frame(CFrame* theContainer);
  CFrame* frame();
  void row(int val);
  int row()const;
  void col(int val);
  int col()const;
  void height(int val);
  int height()const;
  void width(int val);
  int width()const;

These functions set and get the attributes of the CFrame.

CField

The code for this class is provided. You must understand and use it to develop your core classes.

CField is an abstract base class that encapsulates the commonalities of all Input Outputs Console Fields which are placeable on a CDialog. All Fields could be Framed, therefore a CField is inherited from CFrame.

#include "cframe.h"
class CDialog;
class CField : public CFrame{
protected:
  void* _data;
public:
  CField(int Row = 0, int Col = 0,
         int Width = 0, int Height =0,
         void* Data = (void*) 0,
         bool Bordered = false,
         const char* Border=C_BORDER_CHARS);
  ~CField();
  virtual int edit() = 0;
  virtual bool editable() const = 0;
 
 
  virtual void set(const void* data) = 0;
  virtual void* data();
 
  void container(CDialog* theContainer);
  CDialog* container();
};

Attributes

  void* _data;

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

Constructors and Methods

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

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

  ~CField();

Empty Destructor

  virtual int edit() = 0;
  virtual bool editable() const = 0;
  virtual void set(const void* data) = 0;

Enforce the children to implement;

  • an edit() method
  • an editable() method that returns true if the class is to edit data and false if the class is to only display data.
  • a set() method to set the _data attribute to the data the class is to work with.
  virtual void* data();

Returns _data.

  void container(CDialog* theContainer);
  CDialog* container();

Sets and Gets the _frame attribute of CFrame by calling CFrame::frame() method. Make sure to cast The CDialog to CFrame when setting and cast CFrame to CDialog when getting!

CLabel

A readonly Field that encapsulates bio_display() function. (i.e it is responsible to display a short character string on the display) CLable although, by inheritance is Frame, but it is never bordered.

#include "cfield.h"
class CLabel :  public CField{
   int _length;
 public:
   CLabel(const char *Str, int Row, int Col,
     int Len = 0);
   CLabel(int Row, int Col, int Len);
   CLabel(const CLabel& L);
   ~CLabel();
   void draw(int fn=C_NO_FRAME) ;
   int edit();
   bool editable()const;
   void set(const void* str);
};

Attributes

   int _length;

Holds the Length of the label, this will be stored to be passed to bio_display function.

Constructors / Destructor

   CLabel(const char *Str, int Row, int Col,
     int Len = 0);

passes the Row and Col to the CField constructor and then; if len is zero, it will allocate enough memory to store the string pointed by Str and then copies the Str into it. if len > 0, then it will allocate enough memory to store len chars in a string. In any way, the allocated memory is pointed by _data

   CLabel(int Row, int Col, int Len);

Works exactly like the previous constructor, but len in this case can not be zero. (no validation required) and the string pointed by _data will be set to an empty string.

   CLabel(const CLabel& L);

Copy Constructor

   ~CLabel();

makes sure that memory pointed by _data is deallocated before the object is destroyed.

Methods

   void draw(int fn=C_NO_FRAME) ;

makes a direct call to bio_display, passing _data for the string to be printed and absRow() and absCol() for row and col and _length for len. this function ignores the argument fn.

   int edit();

calls draw, returning 0.

   bool editable()const;

always return false.

   void set(const void* str);

if _length is greater than zero, it will copy the string pointed by str into the string pointed by _data upto _length characters. if _length is zero, it will delete the memory pointed by _data and reallocates enough memory for str and copies the string pointed by str into the newly allocated memory pointed by _data.

CDialog (Under Construction)

Organizes CField objects on the screen, displays them and then lets the user edit them one by one.

#pragma once
#include "iolgh.h"
#include "cframe.h"
class CField;
 
class CDialog: public CFrame{
  private:
  int _fnum;
  int _curidx;
  CField* _fld[C_MAX_NO_FIELDS];
  bool _dyn[C_MAX_NO_FIELDS];
  bool _editable;
  public:
  CDialog(CFrame *Container = (CFrame*)0,
           int Row = -1, int Col = -1, 
           int Width = -1, int Height = -1, 
           bool Borderd = false,
           const char* Border=C_BORDER_CHARS);
  virtual ~CDialog();
  void draw(int fn = C_FULL_FRAME);
  int edit(int fn = C_FULL_FRAME);
// all the add methods are to be done by students
  int add(CField* field, bool dynamic = true);
  int add(CField& field, bool dynamic = false);
  CDialog& operator<<(CField* field);
  CDialog& operator<<(CField& field);

  bool editable();
  int fieldNum()const;
  int curIndex()const;
// operator [] is to be done by students
  CField& operator[](unsigned int index);
  CField& curField();
};

Attributes

Mandatory

  int _fnum;

Holds the number of Fields added to the Dialog

  bool _editable;

will be set to true if any of the Fields added are editable.

Optional

This is optional because it depends on how you are going to implement the collection of CFields:

  int _curidx;

Holds the index of the Field that is currently being edited.

  CField* _fld[C_MAX_NO_FIELDS];

Array of CField pointers to hold the address of the CField objects added to the screen.

  bool _dyn[C_MAX_NO_FIELDS];

Holds series of boolean to the exact number of fields, and each boolean here will hold false if the corresponding field pointed by _fld is allocated dynamically or not. This array will later on be used by destructor to decide which object is dynamic and to be deleted.

Constructors/Destructors

  CDialog(CFrame *Container = (CFrame*)0,
           int Row = -1, int Col = -1, 
           int Width = -1, int Height = -1, 
           bool Borderd = false,
           const char* Border=C_BORDER_CHARS);

The constructor, passes all the incoming arguments to the corresponding arguments of the apparent constructor CFrame.
Then it will set called a attributes to their default values and then sets all the field pointers (_fld) to NULL. It also sets all the dynamic (_dyn) flags to false.

  virtual ~CDialog();

The destructor, will loop through all the field pointers and if the corresponding dynamic flag is true then it will delete the field pointed to by the field pointer.

Methods

  void draw(int fn = C_FULL_FRAME);

If fn is C_FULL_FRAME, it will call its parent draw. Then It will draw all the Fields in the Dialog.
If fn is not C_FULL_FRAME, 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 = C_FULL_FRAME);

If CDialog 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(CField* field, bool dynamic = true);

Adds the CField' pointed by field to the Fields of the Dialog; by appending the value of the field pointer after the last added field in the _fld array , setting the corresponding _dyn element to the value of dynamic argument and then increasing _fnum by one and returning it.
important note:
Make sure that add() sets the container of the added CField to this CDialog object, using the container() method of CField

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

Makes a direct call to the first add method.

  CDialog& operator<<(CField* field);

Makes a direct call to the first add method, ignoring the second argument and then returns the owner (current CDialog).

  CDialog& operator<<(CField& field);

Makes a direct call to the second add method, ignoring the second argument and then returns the owner (current CDialog).

  bool editable();

Returns _editable;

  int fieldNum()const;

returns _fnum.

  int curIndex()const;

returns _curidx;

  CField& operator[](unsigned int index);

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

  CField& curField();

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