From 11dcecc3c180e5255ea80597181bf1957bd27530 Mon Sep 17 00:00:00 2001 From: Lesterpig Date: Fri, 8 Apr 2016 16:12:01 +0200 Subject: [PATCH] [d] Add some documentation --- dfssd/gui/colors.go | 2 ++ dfssd/gui/events.go | 6 ++++++ dfssd/gui/graphics.go | 15 ++++++++++++--- dfssd/gui/save.go | 2 ++ dfssd/gui/structures.go | 2 ++ dfssd/gui/window.go | 13 +++++++++++++ 6 files changed, 37 insertions(+), 3 deletions(-) diff --git a/dfssd/gui/colors.go b/dfssd/gui/colors.go index f4e2a11..384c1e9 100644 --- a/dfssd/gui/colors.go +++ b/dfssd/gui/colors.go @@ -1,5 +1,7 @@ package gui +// This file stores useful colors + import "github.com/visualfc/goqt/ui" var colors = map[string]uint32{ diff --git a/dfssd/gui/events.go b/dfssd/gui/events.go index 215ec90..e03d81d 100644 --- a/dfssd/gui/events.go +++ b/dfssd/gui/events.go @@ -1,5 +1,7 @@ package gui +// This file handles event timers and imports. + import ( "fmt" "math" @@ -45,6 +47,7 @@ func (w *Window) AddEvent(e *api.Log) { } } +// DrawEvent triggers the appropriate draw action for a spectific event. func (w *Window) DrawEvent(e *Event) { xa, ya := w.GetClientPosition(e.Sender) xb, yb := w.GetClientPosition(e.Receiver) @@ -62,6 +65,7 @@ func (w *Window) DrawEvent(e *Event) { w.DrawArrow(xa, ya, xb, yb, colors[color]) } +// PrintQuantumInformation triggers the update of the "x / y" quantum information. func (w *Window) PrintQuantumInformation() { if len(w.scene.Events) == 0 { w.progress.SetText("No event") @@ -80,6 +84,7 @@ func (w *Window) PrintQuantumInformation() { w.progress.SetText(fmt.Sprint(currentQuantum, " / ", nbQuantum)) } +// initTimer is called during window initialization. It initializes the timeout signal called for each refresh. func (w *Window) initTimer() { w.timer = ui.NewTimerWithParent(w) @@ -128,6 +133,7 @@ func (w *Window) initTimer() { }) } +// identifierToIndex is used to retrieve a client index from its name, inserting a new client if needed. func (s *Scene) identifierToIndex(identifier string) int { if identifier == "platform" { return -1 diff --git a/dfssd/gui/graphics.go b/dfssd/gui/graphics.go index b8fd333..d83d8bd 100644 --- a/dfssd/gui/graphics.go +++ b/dfssd/gui/graphics.go @@ -1,14 +1,18 @@ package gui +// This file handles complex graphic primitives for the demonstrator. + import ( "math" "github.com/visualfc/goqt/ui" ) -const ARROW_T = math.Pi / 6 -const ARROW_L = 15 +// These two constants are used to configure arrows +const ARROW_T = math.Pi / 6 // angle +const ARROW_L = 15 // side length +// DrawClients draws the different clients in a circle. func (w *Window) DrawClients() { scene := w.graphics.Scene() for i, c := range w.scene.Clients { @@ -25,6 +29,7 @@ func (w *Window) DrawClients() { } } +// GetClientPosition translates a client index into its cartesian coordinates. func (w *Window) GetClientPosition(i int) (x, y float64) { if i < 0 { return w.GetServerPosition(i == -1) @@ -35,6 +40,7 @@ func (w *Window) GetClientPosition(i int) (x, y float64) { return math.Cos(angle) * (w.circleSize / 2), math.Sin(angle) * (w.circleSize / 2) } +// GetServerPosition translates a server into its cartesian coordinates. func (w *Window) GetServerPosition(platform bool) (x, y float64) { x = w.circleSize/2 + 150 y = 0 @@ -44,12 +50,13 @@ func (w *Window) GetServerPosition(platform bool) (x, y float64) { return } +// DrawServers draws the DFSS main servers (ttp and platform) func (w *Window) DrawServers() { scene := w.graphics.Scene() ttp := scene.AddPixmap(w.pixmaps["ttp"]) x, y := w.GetServerPosition(false) - ttp.SetPosFWithXY(x-32, y-16) + ttp.SetPosFWithXY(x-32, y-16) // we are shifting here a bit for better arrow display ttp.SetToolTip("TTP") platform := scene.AddPixmap(w.pixmaps["platform"]) @@ -58,6 +65,7 @@ func (w *Window) DrawServers() { platform.SetToolTip("Platform") } +// DrawArrow is the graphic primitive for drawing an arrow between A and B points func (w *Window) DrawArrow(xa, ya, xb, yb float64, rgb uint32) { scene := w.graphics.Scene() @@ -94,6 +102,7 @@ func (w *Window) DrawArrow(xa, ya, xb, yb float64, rgb uint32) { w.currentArrows = append(w.currentArrows, arrow) } +// RemoveArrows remove every arrow present in the graphic area, and delete them for better memory management. func (w *Window) RemoveArrows() { scene := w.graphics.Scene() diff --git a/dfssd/gui/save.go b/dfssd/gui/save.go index 85b0cf7..d230c49 100644 --- a/dfssd/gui/save.go +++ b/dfssd/gui/save.go @@ -1,5 +1,7 @@ package gui +// This file handles open/save feature. + import ( "encoding/json" "io/ioutil" diff --git a/dfssd/gui/structures.go b/dfssd/gui/structures.go index f646c6a..209fd85 100644 --- a/dfssd/gui/structures.go +++ b/dfssd/gui/structures.go @@ -1,5 +1,7 @@ package gui +// This file stores strucutures used in GUI for fast documentation. + import ( "time" diff --git a/dfssd/gui/window.go b/dfssd/gui/window.go index 579772f..8ea71a9 100644 --- a/dfssd/gui/window.go +++ b/dfssd/gui/window.go @@ -1,5 +1,9 @@ +// Package gui is the graphic part of the dfssd program. package gui +// This file is the entry point of the gui package. +// It handles window instantiation and basic operations on it. + import ( "math" "time" @@ -8,6 +12,7 @@ import ( "github.com/visualfc/goqt/ui" ) +// NewWindow creates and initialiaze a new dfssd main window. func NewWindow() *Window { file := ui.NewFileWithName(":/widget.ui") loader := ui.NewUiLoader() @@ -52,17 +57,22 @@ func NewWindow() *Window { return w } +// OnResizeEvent is called by Qt each time an user tries to resize the window. +// We have to redraw the whole scene to adapt. func (w *Window) OnResizeEvent(ev *ui.QResizeEvent) bool { w.initScene() return true } +// Log is used to print a new line in the log area of the window. +// It should be thread-safe. func (w *Window) Log(str string) { str = time.Now().Format("[15:04:05.000] ") + str w.logField.Append(str) w.logField.EnsureCursorVisible() } +// addIcons adds icons to control buttons, since we cannot add them directly in QtCreator. func (w *Window) addIcons() { w.SetWindowIcon(ui.NewIconWithFilename(":/images/node_magnifier.png")) @@ -79,6 +89,7 @@ func (w *Window) addIcons() { w.replayButton.SetIcon(i) } +// addActions adds action listenners to interactive parts of the window. func (w *Window) addActions() { // MENU BAR openAct := ui.NewActionWithTextParent("&Open", w) @@ -125,6 +136,8 @@ func (w *Window) addActions() { }) } +// initScene creates the Qt graphic scene associated to our custom scene. +// It draws the base circle, clients and servers, and do some memory management for us. func (w *Window) initScene() { // Save old scene oldScene := w.graphics.Scene() -- GitLab