Difference between revisions of "Kexi/Junior Jobs/Add d-pointers"

Jump to: navigation, search
(Introduction)
m
 
(65 intermediate revisions by 3 users not shown)
Line 1: Line 1:
<div style="float:right;padding:1em;">http://dot.kde.org/sites/dot.kde.org/files/GCI_2011_logo_URL_blueborder-nowww.jpeg</div>
+
'''Status: done'''<div style="float:right;padding:1em;">https://developers.google.com/open-source/gci/2012/logo.png</div>
  
*OPEN, DIFFICULTY=2/5
+
*maintainer of this task: staniek at kde.org
*Recommended for [http://www.google-melange.com/gci/homepage/google/gci2011 Google Code-IN] program
+
*DIFFICULTY=2/5
 +
*Offered within [http://www.google-melange.com/gci/homepage/google/gci2012 Google Code-IN] program; splitted to two tasks:
 +
**[http://www.google-melange.com/gci/task/view/google/gci2012/7971213 Part 1]
 +
**[https://google-melange.appspot.com/gci/task/view/google/gci2012/8009216 Part 2]
  
 
==Goal==
 
==Goal==
Improve internal APIs in Kexi. This can be done easily by introducing d-poitners to classes that lack them.
+
Improve internal APIs in Kexi. This can be done easily by introducing d-pointers to classes that lack them.
 +
 
 
==Introduction==
 
==Introduction==
 
Read section about d-pointers on [http://techbase.kde.org/Policies/Library_Code_Policy#D-Pointers|KDE Techbase] (d-pointers only, not shared d-pointers).
 
Read section about d-pointers on [http://techbase.kde.org/Policies/Library_Code_Policy#D-Pointers|KDE Techbase] (d-pointers only, not shared d-pointers).
Line 11: Line 15:
 
Classes that have to be converted are in this form:
 
Classes that have to be converted are in this form:
  
 +
<source lang="cpp-qt">
 
  // MyClass.h
 
  // MyClass.h
 
  class MyClass {
 
  class MyClass {
Line 23: Line 28:
 
   m_foo/doSomething();
 
   m_foo/doSomething();
 
  }
 
  }
 +
</source>
  
 
After converting to d-pointer it should be:
 
After converting to d-pointer it should be:
  
 +
<source lang="cpp-qt">
 
  // MyClass.h
 
  // MyClass.h
 
  class MyClass {
 
  class MyClass {
Line 52: Line 59:
 
   delete d;
 
   delete d;
 
  }
 
  }
 +
</source>
 +
 +
==Further tasks==
 +
Converting non-trivial classes to use d-pointer may also require:
 +
*any code in the class' .cpp file referring to m_foo attribute should be changed to d->foo
 +
*if there were public or protected member variables, move them to the d-pointer class and add accessors and setters for them as in the example below. Read about guildelines for accessors and setters on [http://techbase.kde.org/Policies/Library_Code_Policy#Naming_Conventions Techbase].
 +
<source lang="cpp-qt">
 +
// MyClass.h
 +
class MyClass {
 +
public:
 +
  MyClass();
 +
  bool isBlack;
 +
};
 +
</source>
 +
 +
After converting to d-pointer it should be:
 +
 +
<source lang="cpp-qt">
 +
// MyClass.h
 +
class MyClass {
 +
public:
 +
  MyClass();
 +
  bool isBlack() const; // notice the const
 +
  void setBlack(bool black);
 +
private:
 +
  class Private;
 +
  Private * const d;
 +
};
 +
 +
// MyClass.cpp
 +
class MyClass::Private {
 +
public:
 +
  Private()
 +
  bool isBlack;
 +
};
 +
 +
MyClass::MyClass()
 +
  : d(new Private)
 +
{
 +
  d->foo.doSomething();
 +
}
 +
 +
MyClass::~MyClass()
 +
{
 +
  delete d;
 +
}
 +
 +
bool isBlack() const
 +
{
 +
  return d->isBlack;
 +
}
 +
void setBlack(bool black)
 +
{
 +
  d->isBlack = black;
 +
}
 +
</source>
 +
 +
*The class typically should be "non-copyable" and thus add Q_DISABLE_COPY(...) line in private section of the class as presented below to avoid copying what would conflict with the d-pointer. This macro disables copy constructor and assignment operator. See the [http://doc.qt.io/qt-5/qobject.html#Q_DISABLE_COPY Qt docs] for more information.
 +
<source lang="cpp-qt">
 +
class MyClass
 +
{                                                                 
 +
  // ...
 +
private:
 +
  Q_DISABLE_COPY(MyClass)
 +
  // ...
 +
};
 +
</source>
 +
*Alter any code outside of the class that uses the class' API so that the code compiles and runs in exactly the same way as before.
 +
*If there is inline code in header file that uses member variable, move the variable to d-pointer class if you know for sure the inline code isn't there for optimization. If unsure, ask the mentor or the task maintainer.
 +
*After the work is done, the code should be compiled and possibly the program should be executed to check if there are no regressions.
 +
 +
==List of files==
 +
This list can be extended if student finished the work. If you're looking for more please contact the mentor. Please prepend items with with [done] tag here when done. Please do not change any other APIs without prior contacting the mentor. '''Please read Notes below''' and make sure you understand them (as if unsure).
 +
 +
===Part 1===
 +
For [http://www.google-melange.com/gci/task/view/google/gci2012/7971213 Part 1] of the task.
 +
 +
 +
*In kexi/widget/
 +
**[done]kexicharencodingcombobox.*
 +
**[done]kexidbconnectionwidget.*
 +
**[done]kexidbdrivercombobox.*
 +
**[done]KexiConnectionSelectorWidget.* (not submitted)
 +
**[done]KexiProjectSelectorWidget.*
 +
**[done]kexiscrollview.*
 +
**[done]KexiNameDialog.* (not submitted)
 +
**[done]KexiNameWidget.* (not submitted)
 +
**[done]KexiTableViewColumn.* (not submitted)
 +
**[done]kexidataawarepropertyset.* (not submitted)
 +
**[done]kexidataawareview.* (not submitted)
 +
**[done]KexiFieldListModelItem.* (not submitted)
 +
**[done]KexiFieldListView.* (not submitted)
 +
**[done]kexislider.* (not submitted)
 +
**[done]KexiProjectModelItem.* (not submitted)
 +
**[done]KexiProjectNavigator.* (not submitted)
 +
**[done]KexiDockableWidget.* (not submitted)
 +
**[done]kexicomboboxdropdownbutton.* (not submitted)
 +
**[done]kexidatetimeformatter.* (not submitted)
 +
**[done]kexitooltip.* (not submitted)
 +
 +
*In kexi/plugins/forms/
 +
**[done]kexiformscrollview.*
 +
**[done]kexiformview.* (not submitted)
 +
**[done]kexidbutils.* (not submitted)
 +
 +
*In kexi/plugins/reports/
 +
**[done]kexireportdata.* (not submitted)
 +
**[done]kexisourceselector.* (not submitted)
 +
**[done]keximigratereportdata.* (not submitted)
 +
 +
*In kexi/plugins/importexport/csv/
 +
**[done]kexicsvwidgets.* (not submitted)
 +
 +
*In kexi/migration/
 +
**[done]importwizard.* (not submitted)
 +
**[done]keximigrate.* (not submitted)
 +
 +
===Part 2===
 +
For [https://google-melange.appspot.com/gci/task/view/google/gci2012/8009216 Part 2] of the task.
 +
 +
*In kexi/core/
 +
**[done]kexidataiteminterface.*
 +
**[done]kexiinternalpart.*
 +
**[done]kexipartmanager.*
 +
**[done]kexiprojectconnectiondata.*
 +
**[done]kexistartupdata.*
 +
**[done]kexitextmsghandler.*
 +
**[done]KexiView.* (just m_defaultIconName)
 +
 +
*In kexi/main/
 +
**[done]KexiStartup.*
 +
**[done]KexiTemplatesModel.*
 +
 +
*In kexi/kexiutils/
 +
**[done]FlowLayout.* (and move all inline code to .cpp)
 +
**[done]longlongvalidator.*
 +
**[done]SmallToolButton.* (KexiToolBarSeparator)
  
==Extra tasks needed==
+
*In kexi/formeditor/
After converting to d-pointer:
+
**[done]connectiondialog.*
*any code referring to m_foo attribute should be changed to d->foo
+
**[done]container.*
*if there is inline code in header file that uses member variable, do not move the variable to d-pointer unless you know for sure it isn't there for optimization
+
**[done]events.*
 +
**[done]FormWidget.*
 +
**[done]kexiformeventhandler.*
 +
**[done]libactionwidget.*
 +
**[done]objecttree.*
 +
**[done]resizehandle.*
 +
**[done]richtextdialog.*
 +
**[done]tabstopdialog.*
 +
**[done]widgetfactory.*
 +
**[done]WidgetTreeWidget.*
 +
**[done]widgetwithsubpropertiesinterface.*
  
 
==Required skills==
 
==Required skills==
Basic Qt, average C++.
+
Average C++ needed, at least beginner, Qt knowledge welcome.
*Work within a new branch kexi-dpointers-gci, please create.  
 
  
==Notes to mentor==
+
==Notes==
 +
*To start, build Kexi ([[Calligra/Building]]) from master git branch
 +
*If you want to write proper code, please get accustomed with KDE Policies [http://techbase.kde.org/Policies Policies], especially coding style (inherited from KDElibs) policies; see also [http://techbase.kde.org/Development/Tutorials/Common_Programming_Mistakes Common programming mistakes]
 +
*A lot of changes will be needed to make Kexi build properly again after removing m_* attributes (getters/setters will be used instead of attributes)
 +
*Please take care about constness of returned value (if needed), make getters const, and setters non-const
 +
*Do not return by reference -- use the advantage of [http://doc.qt.digia.com/qt/implicit-sharing.html implicit sharing]
 +
*If the attribute was private, do not add getter/setter for it
 +
*If the attribute was protected, add protected getter/setter for it
 +
*If the attribute was public, add public getter/setter for it
 +
*Do not add d-pointer to internal structures, often indicated by *_p.h name of the header (this makes no sense)
 +
*This task can be naturally splited to many students but please have consistency in mind
 +
*Results are stored within a new branch kexi-dpointers-gci, should be created and maintained by mentor
 +
*The resulting patche(s) should be also uploaded to http://git.reviewboard.kde.org:
 +
**split patches per-directory (e.g. kexi/widget/) to make the patches smaller (so it's easier to review)
 +
**For more comfortable work: on reviewboard, when given issue gets fixed, please click Fixed button; see [http://www.reviewboard.org/docs/manual/1.7/users/reviews/issue-tracking/#responding-to-issues]
 +
*The final commits to git will go to the '''master''' branch and should be splitted per class
 +
*The mentor should synchronize students' work within the single branch
 
*Please always emphasize importance of coding style to students and check that - it's so easier to maintain the style from day one instead of fixing afterwards. Show [http://techbase.kde.org/Policies/Kdelibs_Coding_Style Techbase articles] for that.
 
*Please always emphasize importance of coding style to students and check that - it's so easier to maintain the style from day one instead of fixing afterwards. Show [http://techbase.kde.org/Policies/Kdelibs_Coding_Style Techbase articles] for that.
 
*Take care of coding practices too (see [http://techbase.kde.org/Development/Tutorials/Common_Programming_Mistakes Techbase articles])
 
*Take care of coding practices too (see [http://techbase.kde.org/Development/Tutorials/Common_Programming_Mistakes Techbase articles])

Latest revision as of 21:58, 1 September 2017

Status: done

logo.png
  • maintainer of this task: staniek at kde.org
  • DIFFICULTY=2/5
  • Offered within Google Code-IN program; splitted to two tasks:

Goal

Improve internal APIs in Kexi. This can be done easily by introducing d-pointers to classes that lack them.

Introduction

Read section about d-pointers on Techbase (d-pointers only, not shared d-pointers).

Classes that have to be converted are in this form:

 // MyClass.h
 class MyClass {
 public:
  MyClass();
 private:
  Foo m_foo;
 };
 
 // MyClass.cpp
 MyClass::MyClass() {
  m_foo/doSomething();
 }

After converting to d-pointer it should be:

 // MyClass.h
 class MyClass {
 public:
  MyClass();
 private:
  class Private;
  Private * const d;
 };
 
 // MyClass.cpp
 class MyClass::Private {
 public:
  Private() 
  Foo foo;
 };
 
 MyClass::MyClass()
  : d(new Private)
 {
  d->foo.doSomething();
 }
 
 MyClass::~MyClass()
 {
  delete d;
 }

Further tasks

Converting non-trivial classes to use d-pointer may also require:

  • any code in the class' .cpp file referring to m_foo attribute should be changed to d->foo
  • if there were public or protected member variables, move them to the d-pointer class and add accessors and setters for them as in the example below. Read about guildelines for accessors and setters on Techbase.
 // MyClass.h
 class MyClass {
 public:
  MyClass();
  bool isBlack;
 };

After converting to d-pointer it should be:

 // MyClass.h
 class MyClass {
 public:
  MyClass();
  bool isBlack() const; // notice the const
  void setBlack(bool black);
 private:
  class Private;
  Private * const d;
 };
 
 // MyClass.cpp
 class MyClass::Private {
 public:
  Private() 
  bool isBlack;
 };
 
 MyClass::MyClass()
  : d(new Private)
 {
  d->foo.doSomething();
 }
 
 MyClass::~MyClass()
 {
  delete d;
 }
 
 bool isBlack() const
 {
  return d->isBlack;
 }
 void setBlack(bool black)
 {
  d->isBlack = black;
 }
  • The class typically should be "non-copyable" and thus add Q_DISABLE_COPY(...) line in private section of the class as presented below to avoid copying what would conflict with the d-pointer. This macro disables copy constructor and assignment operator. See the Qt docs for more information.
 class MyClass
 {                                                                   
  // ...
 private:
  Q_DISABLE_COPY(MyClass)
  // ...
 };
  • Alter any code outside of the class that uses the class' API so that the code compiles and runs in exactly the same way as before.
  • If there is inline code in header file that uses member variable, move the variable to d-pointer class if you know for sure the inline code isn't there for optimization. If unsure, ask the mentor or the task maintainer.
  • After the work is done, the code should be compiled and possibly the program should be executed to check if there are no regressions.

List of files

This list can be extended if student finished the work. If you're looking for more please contact the mentor. Please prepend items with with [done] tag here when done. Please do not change any other APIs without prior contacting the mentor. Please read Notes below and make sure you understand them (as if unsure).

Part 1

For Part 1 of the task.


  • In kexi/widget/
    • [done]kexicharencodingcombobox.*
    • [done]kexidbconnectionwidget.*
    • [done]kexidbdrivercombobox.*
    • [done]KexiConnectionSelectorWidget.* (not submitted)
    • [done]KexiProjectSelectorWidget.*
    • [done]kexiscrollview.*
    • [done]KexiNameDialog.* (not submitted)
    • [done]KexiNameWidget.* (not submitted)
    • [done]KexiTableViewColumn.* (not submitted)
    • [done]kexidataawarepropertyset.* (not submitted)
    • [done]kexidataawareview.* (not submitted)
    • [done]KexiFieldListModelItem.* (not submitted)
    • [done]KexiFieldListView.* (not submitted)
    • [done]kexislider.* (not submitted)
    • [done]KexiProjectModelItem.* (not submitted)
    • [done]KexiProjectNavigator.* (not submitted)
    • [done]KexiDockableWidget.* (not submitted)
    • [done]kexicomboboxdropdownbutton.* (not submitted)
    • [done]kexidatetimeformatter.* (not submitted)
    • [done]kexitooltip.* (not submitted)
  • In kexi/plugins/forms/
    • [done]kexiformscrollview.*
    • [done]kexiformview.* (not submitted)
    • [done]kexidbutils.* (not submitted)
  • In kexi/plugins/reports/
    • [done]kexireportdata.* (not submitted)
    • [done]kexisourceselector.* (not submitted)
    • [done]keximigratereportdata.* (not submitted)
  • In kexi/plugins/importexport/csv/
    • [done]kexicsvwidgets.* (not submitted)
  • In kexi/migration/
    • [done]importwizard.* (not submitted)
    • [done]keximigrate.* (not submitted)

Part 2

For Part 2 of the task.

  • In kexi/core/
    • [done]kexidataiteminterface.*
    • [done]kexiinternalpart.*
    • [done]kexipartmanager.*
    • [done]kexiprojectconnectiondata.*
    • [done]kexistartupdata.*
    • [done]kexitextmsghandler.*
    • [done]KexiView.* (just m_defaultIconName)
  • In kexi/main/
    • [done]KexiStartup.*
    • [done]KexiTemplatesModel.*
  • In kexi/kexiutils/
    • [done]FlowLayout.* (and move all inline code to .cpp)
    • [done]longlongvalidator.*
    • [done]SmallToolButton.* (KexiToolBarSeparator)
  • In kexi/formeditor/
    • [done]connectiondialog.*
    • [done]container.*
    • [done]events.*
    • [done]FormWidget.*
    • [done]kexiformeventhandler.*
    • [done]libactionwidget.*
    • [done]objecttree.*
    • [done]resizehandle.*
    • [done]richtextdialog.*
    • [done]tabstopdialog.*
    • [done]widgetfactory.*
    • [done]WidgetTreeWidget.*
    • [done]widgetwithsubpropertiesinterface.*

Required skills

Average C++ needed, at least beginner, Qt knowledge welcome.

Notes

  • To start, build Kexi (Calligra/Building) from master git branch
  • If you want to write proper code, please get accustomed with KDE Policies Policies, especially coding style (inherited from KDElibs) policies; see also Common programming mistakes
  • A lot of changes will be needed to make Kexi build properly again after removing m_* attributes (getters/setters will be used instead of attributes)
  • Please take care about constness of returned value (if needed), make getters const, and setters non-const
  • Do not return by reference -- use the advantage of implicit sharing
  • If the attribute was private, do not add getter/setter for it
  • If the attribute was protected, add protected getter/setter for it
  • If the attribute was public, add public getter/setter for it
  • Do not add d-pointer to internal structures, often indicated by *_p.h name of the header (this makes no sense)
  • This task can be naturally splited to many students but please have consistency in mind
  • Results are stored within a new branch kexi-dpointers-gci, should be created and maintained by mentor
  • The resulting patche(s) should be also uploaded to http://git.reviewboard.kde.org:
    • split patches per-directory (e.g. kexi/widget/) to make the patches smaller (so it's easier to review)
    • For more comfortable work: on reviewboard, when given issue gets fixed, please click Fixed button; see [1]
  • The final commits to git will go to the master branch and should be splitted per class
  • The mentor should synchronize students' work within the single branch
  • Please always emphasize importance of coding style to students and check that - it's so easier to maintain the style from day one instead of fixing afterwards. Show Techbase articles for that.
  • Take care of coding practices too (see Techbase articles)

This page was last edited on 1 September 2017, at 21:58. Content is available under Creative Commons License SA 4.0 unless otherwise noted.