Merge pull request #2121 from verilog-to-routing/Seb_DrawDocumentation

Documentation Updates for VPR Graphics

Author: SebastianLievano

doc/src/api/vprinternals/draw_files.rst

@@ -0,0 +1,123 @@
+===============
+VPR Draw Files
+===============
+
+breakpoint.h/cpp
+--------------
+.. doxygenfile:: breakpoint.h
+   :project: vpr
+   :sections: detaileddescription
+
+draw_basic.h/cpp
+--------------
+.. doxygenfile:: draw_basic.h
+   :project: vpr
+   :sections: detaileddescription
+
+draw_color.h
+--------------
+.. doxygenfile:: draw_color.h
+   :project: vpr
+   :sections: detaileddescription
+
+draw_debug.h/cpp
+--------------
+.. doxygenfile:: draw_debug.h
+   :project: vpr
+   :sections: detaileddescription
+
+draw_global.h/cpp
+--------------
+.. doxygenfile:: draw_global.h
+   :project: vpr
+   :sections: detaileddescription
+
+draw_mux.h/cpp
+--------------
+.. doxygenfile:: draw_mux.h
+   :project: vpr
+   :sections: detaileddescription
+
+draw_noc.h/cpp
+--------------
+.. doxygenfile:: draw_noc.h
+   :project: vpr
+   :sections: detaileddescription
+
+draw_rr_edges.h/cpp
+--------------
+.. doxygenfile:: draw_rr_edges.h
+   :project: vpr
+   :sections: detaileddescription
+
+draw_rr.h/cpp
+--------------
+.. doxygenfile:: draw_rr.h
+   :project: vpr
+   :sections: detaileddescription
+
+draw_searchbar.h/cpp
+--------------
+.. doxygenfile:: draw_searchbar.h
+   :project: vpr
+   :sections: detaileddescription
+
+draw_toggle_functions.h/cpp
+--------------
+.. doxygenfile:: draw_toggle_functions.h
+   :project: vpr
+   :sections: detaileddescription
+
+draw_triangle.h/cpp
+--------------
+.. doxygenfile:: draw_triangle.h
+   :project: vpr
+   :sections: detaileddescription
+
+draw_types.h/cpp
+--------------
+.. doxygenfile:: draw_types.h
+   :project: vpr
+   :sections: detaileddescription
+
+draw.h/cpp
+--------------
+.. doxygenfile:: draw.h
+   :project: vpr
+   :sections: detaileddescription
+
+hsl.h/cpp
+--------------
+.. doxygenfile:: hsl.h
+   :project: vpr
+   :sections: detaileddescription
+
+intra_logic_block.h/cpp
+--------------
+.. doxygenfile:: intra_logic_block.h
+   :project: vpr
+   :sections: detaileddescription
+
+manual_moves.h/cpp
+--------------
+.. doxygenfile:: manual_moves.h
+   :project: vpr
+   :sections: detaileddescription
+
+save_graphics.h/cpp
+--------------
+.. doxygenfile:: save_graphics.h
+   :project: vpr
+   :sections: detaileddescription
+
+search_bar.h/cpp
+--------------
+.. doxygenfile:: search_bar.h
+   :project: vpr
+   :sections: detaileddescription
+
+ui_setup.h/cpp
+--------------
+.. doxygenfile:: ui_setup.h
+   :project: vpr
+   :sections: detaileddescription

doc/src/api/vprinternals/draw_structs.rst

@@ -0,0 +1,15 @@
+===============
+VPR Draw Structures
+===============
+
+T_Draw_State
+----------
+.. doxygenstruct:: t_draw_state
+   :project: vpr
+   :members:
+
+T_Draw_Coords
+----------
+.. doxygenstruct:: t_draw_coords
+   :project: vpr
+   :members:

doc/src/api/vprinternals/index.rst

@@ -0,0 +1,11 @@
+.. _vpr_internals:
+
+VPR INTERNALS
+=======
+
+.. toctree::
+   :maxdepth: 1
+
+   draw_structs
+   vpr_ui
+   draw_files

doc/src/api/vprinternals/vpr_ui.rst

@@ -0,0 +1,9 @@
+=============================
+VPR UI
+=============================
+
+UI SETUP
+-------
+.. doxygenfile:: ui_setup.h
+   :project: vpr
+   :sections: func

doc/src/dev/tutorials/edit_vpr_ui.rst

@@ -0,0 +1,9 @@
+.. _edit_vpr_ui:
+
+Editing VPR UI
+--------------
+
+VPR's UI is created with GTK, and actively maintained/edited through the use of Glade and a main.ui file. We prefer to not use code initializations of Gtk Buttons/UI objects, and instead make them with Glade. 
+This allows for better organized menus and visual editing of the UI. Please consult the attached guide for Glade: <Link Glade/Gtk quickstart> (WIP as of August 8th, 2022). 
+
+When connecting a button to its function, place it in an appropriate function depending on the drop down menu it will go in. Button setups are done in ui_setup.cpp/h and callback functions are in draw_toggle_functions.cpp/h.

doc/src/dev/tutorials/index.rst

@@ -8,3 +8,4 @@ Developer Tutorials
 
     new_developer_tutorial
     timing_graph_debug/index
+    edit_vpr_ui

doc/src/index.rst

@@ -63,6 +63,7 @@ For more specific documentation about VPR see :ref:`vpr`.
 
    api/vpr/index
    api/vtrutil/index
+   api/vprinternals/index
 
 Indices and tables
 ==================

vpr/src/draw/breakpoint.h

@@ -1,3 +1,21 @@
+/**
+ * @file breakpoint.h
+ * 
+ * @brief Declaration of breakpoint class, as well as some related functions.
+ * 
+ * This file holds the declaration of the breakpoint class, and also some of the breakpoint related functions.
+ * 
+ * This class holds the definiton of type Breakpoint as well as all related functions. 
+ * Breakpoints can be set through the GUI anytime during placement or routing. Breakpoints can also be activated, 
+ * deactivated, and deleted. Each breakpoint has a type (BT_MOVE_NUM, BT_TEMP_NUM, BT_FROM_BLOCK, BT_ROUTER_ITER, BT_ROUTE_NET_ID, BT_EXPRESSION) and holds the 
+ * values for corresponding to its type, as well as a boolean variable to activate and deactivate a breakpoint. It should be noted that each breakpoint can only have one type and hold one value corresponding to that type. 
+ * More complicated breakpoints are set using an expression. (e.g move_num > 3 && block_id == 11) 
+ * Breakpoints can be create using 3 constructors, the default contructor that doesn't identify the type and sets a breakpoint that is never reached, 
+ * a constructor that takes in the type and an int value, and lastly a constructor that takes in the type and the sting that holds the expression. 
+ * (e.g Breakpoint(BT_MOVE_NUM, 4) or Breakpoint(BT_EXPRESSION, "move_num += 3")) The == operator has also been provided which returns true when two 
+ * breakpoints have the same type, and the same value corresponding to the type.
+ */
+
 #ifndef BREAKPOINT_H
 #define BREAKPOINT_H
 
@@ -7,9 +25,6 @@
 #include "move_transactions.h"
 #include "vtr_expr_eval.h"
 
-/**This class holds the definiton of type Breakpoint as well as al realted functions. Breakpoints can be set through the GUI anytime during placement or routing. Breakpoints can also be activated, deactivated, and deleted. Each breakpoint has a type (BT_MOVE_NUM, BT_TEMP_NUM, BT_FROM_BLOCK, BT_ROUTER_ITER, BT_ROUTE_NET_ID, BT_EXPRESSION) and holds the values for corresponding to its type, as well as a boolean variable to activate and deactivate a breakpoint. It should be noted that each breakpoint can only have one type and hold one value corresponding to that type. More complicated breakpoints are set using an expression. (e.g move_num > 3 && block_id == 11) 
- * Breakpoints can be create using 3 constructors, the default contructor that doesn't identify the type and sets a breakopint that is never reached, a constructor that takes in the type and an int value, and lastly a constructor that takes in the type and the sting that holds the expression. (e.g Breakpoint(BT_MOVE_NUM, 4) or Breakpoint(BT_EXPRESSION, "move_num += 3")) The == operator has also been provided which returns true when two breakpoints have the same type, and the same value corresponding to the type.**/
-
 typedef enum breakpoint_types {
     BT_MOVE_NUM,
     BT_TEMP_NUM,

vpr/src/draw/draw.cpp

@@ -8,8 +8,8 @@
  * As a note, looks into draw_global.c for understanding the data structures associated with drawing->
  *
  * Contains all functions that didn't fit in any other draw_*.cpp file.
- * Authors: Vaughn Betz, Long Yu (Mike) Wang, Dingyu (Tina) Yang
- * Last updated: June 2019
+ * Authors: Vaughn Betz, Long Yu (Mike) Wang, Dingyu (Tina) Yang, Sebastian Lievano
+ * Last updated: August 2022
  */
 
 #include <cstdio>
@@ -672,7 +672,7 @@ void act_on_key_press(ezgl::application* app, GdkEventKey* /*event*/, char* key_
     std::string text(gtk_entry_get_text(GTK_ENTRY(searchBar)));
     t_draw_state* draw_state = get_draw_state_vars();
     if (gtk_widget_is_focus(searchBar)) {
-        if (key == "Return") {
+        if (key == "Return" || key == "Tab") {
             enable_autocomplete(app);
             gtk_editable_set_position(GTK_EDITABLE(searchBar), text.length());
             return;
@@ -683,6 +683,9 @@ void act_on_key_press(ezgl::application* app, GdkEventKey* /*event*/, char* key_
     } else {
         gtk_entry_set_completion(GTK_ENTRY(searchBar), nullptr);
     }
+    if (key == "Escape") {
+        deselect_all();
+    }
 }
 
 void act_on_mouse_press(ezgl::application* app, GdkEventButton* event, double x, double y) {

vpr/src/draw/draw.h

@@ -1,3 +1,22 @@
+/**
+ * @file draw.h
+ * 
+ * The main drawing file. Contains the setup for ezgl application, ui setup, and graphis functions
+ * 
+ * This is VPR's main graphics application program. The program interacts with ezgl/graphics.hpp,
+ * which provides an API for displaying graphics on both X11 and Win32. The most important
+ * subroutine in this file is draw_main_canvas(), which is a callback function that will be called 
+ * whenever the screen needs to be updated. Then, draw_main_canvas() will decide what
+ * drawing subroutines to call depending on whether PLACEMENT or ROUTING is shown on screen.
+ * The initial_setup_X() functions link the menu button signals to the corresponding drawing functions. 
+ * As a note, looks into draw_global.c for understanding the data structures associated with drawing->
+ *
+ * Contains all functions that didn't fit in any other draw_*.cpp file.
+ * 
+ * Authors: Vaughn Betz, Long Yu (Mike) Wang, Dingyu (Tina) Yang, Sebastian Lievano
+ * Last updated: August 2022
+ */
+
 #ifndef DRAW_H
 #define DRAW_H