Difference between revisions of "API & Development"

From LibreCAD wiki
Jump to: navigation, search
(Factories:)
m (fixed typo, need glasses ;))
 
(8 intermediate revisions by 3 users not shown)
Line 1: Line 1:
=== Factories: ===
 
  
'''QG_ActionHandler :'''
 
  
Responsible for starting CAD actions
 
  
'''RS_EventHandler : '''
+
=== Qt ===
  
Responsible for routing UI events
+
LibreCAD is a [http://doc.qt.io/qt-5/topics-ui.html widget-based user interface]. <br>
 +
The following has many useful links if you are new to Qt: http://doc.qt.io/qt-5/qtwidgets-index.html
  
'''QG_ActionFactory :'''
+
=== Factories ===
  
Generate GUI actions and connection to CAD actions
+
; QG_ActionHandler
  
'''QG_DialogFactory'''
+
: Responsible for starting CAD actions
  
Access to GUI interface: Qt widgets
+
; RS_EventHandler
  
 +
: Responsible for routing UI events
  
'''RS_Entity'''
+
; QG_ActionFactory
  
Base class for all CAD entity types
+
: Generate GUI actions and connection to CAD actions
 +
 
 +
; QG_DialogFactory
 +
 
 +
: Access to GUI interface: Qt widgets
 +
 
 +
=== Drawing ===
 +
 
 +
; RS_PainterQt
 +
 
 +
: Responsible for the actual drawing of objects (onto a QPaintDevice)
 +
 
 +
=== Undo/Redo ===
 +
 
 +
; RS_Undoable
 +
 
 +
: Base class for all RS_Entity
 +
: This class simply wraps a single flag.
 +
: When false, the entity is valid.
 +
: When true, the entity is undone.
 +
: To undo/redo the entity, the flag has to be toggled.
 +
 
 +
; RS_UndoCycle
 +
: This is a list of entities (RS_Undoable) modified in one transaction (cycle)
 +
 
 +
; RS_Undo
 +
: This is one of RS_Document's base classes
 +
: It keeps a list of RS_UndoCycle, the undo/redo stack
 +
: Each creation/modification is added to the current undo cycle, which is pushed to the list then
 +
: Undo/Redo actions walk up or down the undo cycle list and toggles all entities in one cycle
 +
: On modification entities are not modified immediately, the entity is cloned, the original undone and the clone modified
 +
: With undo, the clone is undone and the original entity redone
 +
 
 +
=== CAD Entities ===
 +
 
 +
; RS_Entity
 +
 
 +
: Base class for all CAD entity types
 +
 
 +
=== RS_GraphicView ===
 +
==== Cleanup mode ====
 +
There are some segfaults by action( rs_action* methods) destructors caused by actions when closing the main window. These segfault can be fixed by detecting RS_GraphicView cleanup in action destructors.
 +
 
 +
A method to detect cleanup is added:
 +
 
 +
bool RS_GraphicView::isCleanUp() const;
 +
 
 +
whenever isCleanUp() returns true, action destructors should not try to cleanup, as entities may be deleted already.
 +
 
 +
TODO: We need a better solution probably by smart pointers.
 +
 
 +
=== RS_Debug ===
 +
==== The --debug switch ====
 +
The LibreCAD binary supports the command line switch --debug. To use this feature, start LC from a terminal appending the --debug parameter.<br>
 +
LibreCAD will start as usual, but in the terminal window a whole lot of debugging messages will appear.<br>
 +
To save these messages into a file use '''librecad --debug 2>debugging.txt'''.
 +
 
 +
{{Warning|This does not apply to Windows! On Windows use the Qt Creator debug console.}}
 +
 
 +
==== The enhanced --debug switch ====
 +
With [https://github.com/LibreCAD/LibreCAD/commit/de0f48fcde1bb9890281c4cdb62e23771b0245fe commit de0f48f] (somewhere after version 2.0.0rc2; Sep 11, 2013), this switch was enhanced.<br>
 +
When debugging a special issue, you can control the debugging level, thus the quantity of messages printed to the terminal will be reduced.<br>
 +
 
 +
Using only --debug is working as always.<br>
 +
Appending a digit from 0 to 6 to the switch, e.g. --debug3, will set the corresponding debugging level.<br>
 +
For a list of all debugging levels use the switch --debug?, then a list of all debugging levels is printed and LibreCAD will not start.<br>
 +
The higher the level number, the more messages will be printed.<br>
 +
 
 +
The supported debug levels are:
 +
{| class="wikitable"
 +
! level
 +
! name
 +
! use in print()
 +
! printing
 +
|-
 +
|align="center"|0||Nothing ||RS_Debug:D_NOTHING||nothing
 +
|-
 +
|align="center"|1||Critical ||RS_Debug:D_CRITICAL||only critical
 +
|-
 +
|align="center"|2||Error ||RS_Debug:D_ERROR||critical and errors
 +
|-
 +
|align="center"|3||Warning ||RS_Debug:D_WARNING||critical, errors and warnings
 +
|-
 +
|align="center"|4||Notice ||RS_Debug:D_NOTICE||critical, errors, warnings and notices
 +
|-
 +
|align="center"|5||Informational ||RS_Debug:D_INFORMATIONAL||critical, errors, warnings, notices and informational
 +
|-
 +
|align="center"|6||Debugging ||RS_Debug:D_DEBUGGING||all, same as --debug
 +
|}
 +
 
 +
==== Using the enhanced --debug switch ====
 +
Use the '''RS_DEBUG->print( level, "format", ...);''' method to print the messages you need.<br>
 +
There is an overloaded method '''RS_DEBUG->print( "format", ...);''' which is the same as '''RS_DEBUG->print( RS_Debug:D_DEBUGGING, "format", ...);'''.<br>
 +
'''"format"''' is a standard '''printf'''-format string, followed by the variables to be set in the format string.<br>
 +
 
 +
When you're working on a new feature or investigating an issue, add e.g. '''RS_DEBUG->print( RS_Debug:D_INFORMATIONAL, ...);''' commands to your code. Start LibreCAD from a terminal with --debug5.<br>
 +
Then you will have much lesser output to search for the information you need.
 +
 
 +
If the messages will be useful for further debugging sessions, you may leave some of them in the code, but consider to raise their level befor committing, to keep the lower levels clean.<br>
 +
If messages are useless after finishing the feature or fixing an issue, please remove them before committing.
 +
 
 +
[[Category:Developers]]

Latest revision as of 15:49, 31 October 2018


Qt

LibreCAD is a widget-based user interface.
The following has many useful links if you are new to Qt: http://doc.qt.io/qt-5/qtwidgets-index.html

Factories

QG_ActionHandler
Responsible for starting CAD actions
RS_EventHandler
Responsible for routing UI events
QG_ActionFactory
Generate GUI actions and connection to CAD actions
QG_DialogFactory
Access to GUI interface: Qt widgets

Drawing

RS_PainterQt
Responsible for the actual drawing of objects (onto a QPaintDevice)

Undo/Redo

RS_Undoable
Base class for all RS_Entity
This class simply wraps a single flag.
When false, the entity is valid.
When true, the entity is undone.
To undo/redo the entity, the flag has to be toggled.
RS_UndoCycle
This is a list of entities (RS_Undoable) modified in one transaction (cycle)
RS_Undo
This is one of RS_Document's base classes
It keeps a list of RS_UndoCycle, the undo/redo stack
Each creation/modification is added to the current undo cycle, which is pushed to the list then
Undo/Redo actions walk up or down the undo cycle list and toggles all entities in one cycle
On modification entities are not modified immediately, the entity is cloned, the original undone and the clone modified
With undo, the clone is undone and the original entity redone

CAD Entities

RS_Entity
Base class for all CAD entity types

RS_GraphicView

Cleanup mode

There are some segfaults by action( rs_action* methods) destructors caused by actions when closing the main window. These segfault can be fixed by detecting RS_GraphicView cleanup in action destructors.

A method to detect cleanup is added:

bool RS_GraphicView::isCleanUp() const;

whenever isCleanUp() returns true, action destructors should not try to cleanup, as entities may be deleted already.

TODO: We need a better solution probably by smart pointers.

RS_Debug

The --debug switch

The LibreCAD binary supports the command line switch --debug. To use this feature, start LC from a terminal appending the --debug parameter.
LibreCAD will start as usual, but in the terminal window a whole lot of debugging messages will appear.
To save these messages into a file use librecad --debug 2>debugging.txt.

Attention yellow.svg Warning: This does not apply to Windows! On Windows use the Qt Creator debug console.

The enhanced --debug switch

With commit de0f48f (somewhere after version 2.0.0rc2; Sep 11, 2013), this switch was enhanced.
When debugging a special issue, you can control the debugging level, thus the quantity of messages printed to the terminal will be reduced.

Using only --debug is working as always.
Appending a digit from 0 to 6 to the switch, e.g. --debug3, will set the corresponding debugging level.
For a list of all debugging levels use the switch --debug?, then a list of all debugging levels is printed and LibreCAD will not start.
The higher the level number, the more messages will be printed.

The supported debug levels are:

level name use in print() printing
0 Nothing RS_Debug:D_NOTHING nothing
1 Critical RS_Debug:D_CRITICAL only critical
2 Error RS_Debug:D_ERROR critical and errors
3 Warning RS_Debug:D_WARNING critical, errors and warnings
4 Notice RS_Debug:D_NOTICE critical, errors, warnings and notices
5 Informational RS_Debug:D_INFORMATIONAL critical, errors, warnings, notices and informational
6 Debugging RS_Debug:D_DEBUGGING all, same as --debug

Using the enhanced --debug switch

Use the RS_DEBUG->print( level, "format", ...); method to print the messages you need.
There is an overloaded method RS_DEBUG->print( "format", ...); which is the same as RS_DEBUG->print( RS_Debug:D_DEBUGGING, "format", ...);.
"format" is a standard printf-format string, followed by the variables to be set in the format string.

When you're working on a new feature or investigating an issue, add e.g. RS_DEBUG->print( RS_Debug:D_INFORMATIONAL, ...); commands to your code. Start LibreCAD from a terminal with --debug5.
Then you will have much lesser output to search for the information you need.

If the messages will be useful for further debugging sessions, you may leave some of them in the code, but consider to raise their level befor committing, to keep the lower levels clean.
If messages are useless after finishing the feature or fixing an issue, please remove them before committing.