(GSoC) Port Cricket to use Toga, instead of Tkinter

[Dayof]

Table of content

1. Abstract 1.1 Drawbacks of the existing GUI framework 1.2 Goals 1.3 Benefits
2. The new framework 2.1 Overview 2.2 Advantages
3. Schedule and milestones 3.1 Prepare the field 3.2 Port Cricket to use Toga 3.3 Usage documentation 3.4 If time permits...
4. About me

1 Abstract

1.1 Drawbacks of the existing GUI framework

Cricket's GUI interface is currently implemented using Tkinter, which has a lot of limitations. For example: Tkinter has no built-in table widget, while Toga does. Tkinter does not support CSS properties for styling the objects, while Toga supports because of the Colosseum framework, the (partial) implementation of the CSS box and the flexbox layout algorithm. Also, the Toga project is very active, the community is always developing and fixing issues, and looks / feels like a native app for multiple platforms.

1.2 Goals

The main goal is the complete port of Cricket to use Toga as the framework for GUI interface. The base logic is mostly complete, so firstly I will plan how to adapt the actual architecture of the view to use Toga widgets. If I find one widget that Cricket uses but isn't implemented on Toga, I will develop a contribution to this specific widget. This way the application will not lose the basics layout.

So, the proposal will not only focus on the port of Tkinter to Toga, but on mapping the necessary widgets for a real application using Toga framework.

1.3 Benefits

In addition of the advantages of using Toga instead of Tkinter as I highlighted on section 1.1, this is a opportunity to improve error handling and make better use of features that Toga has but Tkinter does not. It will be the first BeeWare project that “eats it is own dogwood".

2 The new framework

2.1 Overview

The application logic core will be preserved, migrating only the objects of Tkinter to Toga widgets. Both Tkinter and Toga are event oriented so a redesign of the architecture will not happen.

Example of a simple migration of a widget object of Tkinter to Toga:

Tkinter:

  self.toolbar = Frame(self.root)
  self.toolbar.grid(column=0, row=0, sticky=(W, E))

  self.stop_button = Button(self.toolbar,
                            text='Stop',
                            command=self.cmd_stop,
                            state=DISABLED)
  self.stop_button.grid(column=0, row=0)

Toga:

  box = toga.Box()

  self.stop_button = toga.Button('Stop', on_press=self.cmd_stop, enabled=False)
  button.style.set(width=100, margin_left=10)

  box.add(button)

2.2 Advantages

At the example above we can already see the first advantage of the migration, the CSS usage, allowing more flexibility of the UI design. Also there are widgets that exist only in Toga, like the Table widget. More features can be added from this migration.

3 Schedule and milestones

I am going to two events during the GSOC, one during June 15th-18th and one during the period August 1st-5th. But these events are academic and will not prevent me from working there.

Also, it is important to cite the days that I will probably work half of the time because of the exams I will have on college:

• June 1, 14, and 29
• July 5, 6

3.1 Prepare the field -- first milestone (1 week)

(From May 30 until June 5)

Before starting coding there are a few important things to do around the first week:

• Learn the architecture of Tkinter and Toga
• Review alongside the mentor what is important to maintain from the base code
• Which parts parts of Cricket would be good to add new features from Toga

3.2 Port Cricket to use Toga -- second milestone (9 weeks)

(From June 6 until August 7)

Each part of this milestone will follow a development process cycle: build, test and document. I will focus only on the Cocoa platform on each improvement or development of widgets on Toga. All modifications on Cricket will be made on the files view.py and on main.py. For Toga, the additions/modifications will be made on widgets folder.

To elaborate this section of the proposal I mapped each object used with Tkinter that exists in Toga, some objects need to be explored with more details but the next sub sections will focus on solving the development on a top-down view, solving the "easiest" problems first, such as adapting the complete widgets that exist on Toga already and is used on Cricket.

Aside from modifying the main file, since the GUI is separated on an independent class named MainWindow, there is no need to refactor any other class when the port is complete.

The average time cost to develop a widget was calculated from the time cost that the primary author from the Cricket project, Russell Keith-Magee, developed some new widget or feature to a specific platform (inferred from commits on GitHub), multiplied by 6 to estimate the time that I will take to develop.

3.2.1 Adapt the complete widgets that exist on Toga already and is used on Cricket (8.5 weeks)

3.2.1.1 Core Widgets (1.5 week)

The core widgets available on Toga are Application, Box, Font, Widget and Window, but I will need to adapt only 4 of them, since the utility of the class Widgets on Cricket will be defined later on Tree. The explanation is the following:

• Application

Toga: This core widget is used to manage the main loop of the application and to control the other core widget, Window, setting the title, size and other properties of the main Window.

Tkinter: The title, geometry and other properties of the window on Tkinter also is setup on a core widget of the application, named root.

Result: This adaptation is possible.

• Box

Toga: Box is a container for any widget, so other boxes can be added inside it as well. Also, with the Colosseum integration, the style is made with a partial CSS environment.

Tkinter: The closest similar object of Box on this framework would be the PanedWindow, which allows add other panes inside a bigger pane and modify the styles. The Frame widget is also similar.

Result: This adaptation is possible.

• Font

Toga: Fonts of the labels, modify family and size.

Tkinter: Also allows to modify de family and size, but there are many other options, like, weight, underline, overstrike and slant.

Result: Since is not really necessary to add weight of label this adaptation is possible. If time permits I can add those new properties on Toga.

• Widget

Toga: Base class for widgets, not instantiated directly.

Tkinter: Standard options and commands supported on all widgets. This module is used on Cricket as a event handler when a test case has been selected in the tree.

Result: These event handler explained above will be develop on another widget, Tree. So the adaptation will be made later.

• Window

Toga: Display components to the user, support displaying multiple widgets, toolbars and resizing.

Tkinter: The class more similar to Window is the Frame together with the main class Tk. Then you can set the title on root window, add multiple widgets, toolbar and also resize.

Result: This adaptation is possible.

3.2.1.2 General Widgets (5.5 weeks)

The general widgets available on Toga are Button, Image View, Label, Multiline Text Input, Number Input, Option Container, Progress Bar, Selection, Text Input, Table and Tree, but I'll need adapt only 6 of them. I propose work on 2 widgets per week. The widgets that were cut off from adaptation are the following:

• Image View

Toga: Container for an image to be rendered on the display.

Tkinter: Cricket doesn't use this feature.

Result: There is no need to adapt this widget.

• Multiline Text Input

Toga: Similar to the text input but designed for larger inputs, similar to the text area field of HTML.

Tkinter: Cricket doesn't use this feature.

Result: There is no need to adapt this widget.

• Number Input

Toga: Text input box that is limited to numeric input.

Tkinter: Similar to this class there is Entry, but it is a editable text field widget, not only for number. We'll adapt this kind of widget on Text Input.

Result: There is no need to adapt this widget.

• Selection

Toga: A simple control for allowing the user to choose between a list of string options.

Tkinter: The class similar to this widget is OptionMenu, but Cricket doesn't use it.

Result: There is no need to adapt this widget.

• Table

Toga: Display tabular data. It can be instantiated with the list of headings and then data rows can be added.

Tkinter: Doesn't exist this widget on Tkinter.

Result: There is no need to adapt this widget.

3.2.1.2.1 Basic General Widgets (1.5 week)

• Button

Toga: Basic clickable button. It's possible to modify the label, event on press, state of disable or enable.

Tkinter: On Cricket the button of Tk is used with the same features that the button on Toga offers.

Result: This adaptation is possible.

• Switch

Toga: Switch implements the basics features of the widget that Tkinter has.

Tkinter: They call this feature on Tkinter as Checkbutton.

Result: Probably will need some improvements, like commands and variables to Switch, but the basic adaptation is possible.

• Label

Toga: A text-label for annotating forms or interfaces.

Tkinter: On Cricket the label of Tk is used with the same features that the label on Toga offers.

Result: This adaptation is possible.

3.2.1.2.2 Intermediate General Widgets (1 week)

• Text Input

Toga: A simple input field for user entry of text data.

Tkinter: On Tkinter this widget will have 2 utilities, first to substitute Entry and second ReadOnlyText because there is a set_readonly method.

Result: This adaptation is possible.

• Progress Bar

Toga: Simple widget for showing a percentage progress for task completion.

Tkinter: The important properties of Progress Bar are to set the value and the max to go. There are other properties that this widget have in addition on Tkinter, for example, length, orientation and mode.

Result: The basic implementation of this widget on Toga are enough to adapt on Cricket even without those properties that Tkinter has in advance.

3.2.1.2.3 Advance General Widgets (3 week)

• Option Container

Toga: Is a user-selection control for choosing from a pre-configured list of controls, like a tab view.

Tkinter: There is the class for this on Tkinter, the Notebook, that is a multi-paned container widget.

Result: The object of Tkinter is used on Cricket with the same properties that are available on Toga, so this adaptation is possible.

• Tree

Toga: A scrollable display of heirarchical data.

Tkinter: Hierarchical multicolumn data display widget.

Result: This adaptation is possible.

3.2.1.3 Layout Widgets (1.5 week)

The layout widgets available on Toga are Scroll Container, Split Container and Web View, but I will need adapt only 2 of them. The explanation is the following:

• Scroll Container

Toga: Similar to the iframe or scrollable div element in HTML, it contains an object with its own scrollable selection.

Tkinter: Control the viewport of a scrollable widget.

Result: The final use of these two widget are the same, but the difference is that on Toga you add content on a scroll container and on Tkinter you add a scroll bar on a container, so this adaptation is possible.

• Split Container

Toga: Is a container with a movable split and the option for 2 or 3 elements.

Tkinter: There is no similar widget on Tkinter like Split Container but on Cricket are simulate using two separated Frames.

Result: This adaptation is possible.

• Web View

Toga: Displaying an embedded browser window within an application.

Tkinter: Cricket doesn't use this feature.

Result: There is no need to adapt this widget.

3.2.2 Finishing port (0.5 week)

• Update releases file.
• Update authors file.
• Update roadmap file.

3.3 Usage documentation -- last milestone (2 weeks)

(From August 8 until August 21)

On the tutorials are presented four basic tutorials of the current widgets and its features, but since we are going to add some new small modifications, it would be interesting to show their usage. For example, the new feature of enable/disable a button.

3.3.1 Add new tutorials with new features for Toga (1 week)

There are few widgets present on Toga but there are no basics examples on how to use them, so I will include a basic example of each new widgets that I'll develop on 3.2.1. For example, the widget to add menu and menu items proposed on 3.2.1.

If possible, I will add a tutorial for the other widgets that still lack a basic usage example.

3.4 If time permits...

There are some TODOs on Cricket, like improving GUI interface, including keyboard shortcuts and search, so, if time permits I will follow this sequence.

4 About me

My name is Dayanne Fernandes da Cunha, I'm an undergraduate student of Bachelor on Computer Science at University of Brasília (UnB), Brazil. My time zone is UTC-3. I program in Python for at least 3 years, I program also in C, C++, Java and Javascript. This is my very first experience on contribution for a open source project. I've already made 2 PR this month and I loved it!

Edit: The subsection Improvement of simple widgets on Toga (0.5 week) was removed because the Switch widget does what the CheckButton do. So the Switch was add on the General Widgets section, into Basic General Widgets, bellow the Button port. Also, the '0.5 week' was migrate to the Basic General Widgets subsection.

Edit2: The subsection Development of objects that exist on Cricket but still not implement on Toga (2 weeks) was removed because the Menu builder was add on the commit beeware/toga@9d9c911. The weeks remaining from this section removal was migrate to Advance General Widgets subsection.

[freakboy3742]

This proposal was accepted for the 2017 GSoC. Project progress updates will be posted here by @Dayof.

[Dayof]

Prepare the field (1 week) [OK]

• Learn the architecture of Tkinter and Toga

This task was acomplished when I started to elaborate the proposal with more details about the chunks. To understand what I would need to change on Cricket (view.py), I started mapping what was ready on Toga to use and its (widgets) relation with Tkinter.

Tkinter has an architecture really alike Toga, with a class to start the application, then set the application/ window attributes, like title, geometry, etc. Every widget, core or general, was mapped and written in the proposal.

[Dayof]

• Review alongside the mentor what is important to maintain from the base code and which parts of Cricket would be good to add new features from Toga

In a Skype meeting with the mentor @freakboy3742 was asked these 2 questions, "what is important to maintain from the base code" and "which parts of Cricket would be good to add new features from Toga", and of course, first, he suggested me to take a look on the whole code to understand better what the project (Cricket) does and how it does. And to the second question, we've both agreed to think about this after the whole port of Cricket to Toga, then I could think to add more features or even rethink about the present layout.

For the first question, as a good path to follow, he suggested me to solve a issue on Cricket that he found but wasn't written yet on GitHub. I created this issue on pybee/cricket. I took a look on the problem, recorded a video about the example that he explained and wrote the problem as an issue on the github repository. More details about this issue can be found on the ticket #59.

After reproduce this problem like he told me, I went to search why Cricket was behaviouring like that. I made a top-down search to explore more deeply the problem. First went to view.py, then saw some reference to the general model.py and unittest model.py, then I ended up in executor.py and saw that something was wrong on that part of the program. I read more about the library subprocess, queue, threading, and after all was just a Thread problem, was missing .join() to make the threads wait untill the whole output is appended.

To make sure that the ".join()" has a real effect on the system, a test was made to test the coverage of tests using unittest. This test can be found at test_unit_integration.py with the name TestTestsCoverage.

This issue helped me to understand better the Cricket architecture and what would be good to maintain from the base code.

[Dayof]

Core Widgets (1.5 week) [OK]

• Application

After the preparation on the first week it's time to start the port to Toga! First, I created a new branch on my fork named toga to push the changes that I'll make on the files main.py and view.py.

The first thing that I did was the cleanup of all the Tkinter components, imports, objects, mainloop, etc. I executed the application without these components to make sure that all of Tkinter's components was gone and no sintax error appeared.

After no error complained on the cleanup, I inserted the basic structure to build a Toga application. Imported Toga on both main.py and view.py, I inserted a construction of the object MainWindow with the name and app id of Cricket and started the project view with the view.main_loop().

On the MainWindow side, it was add the inheritance of toga application, the startup method, initialization of some basics structure of Cricket, the name and size of the main window, a basic Box content to show on the main content to test it's functionality and finally the call to show the window, self.main_window.show().

This changes can be seen on the commit ac2ad43.

The errors dialogs also needed some change on the architecture, beginning with the inheritance of Toplevel from Tkinter. This class was removed since the main window widget will be pass as an argument to create this errors dialogs. Also, was created properties to warn the MainWindow if there is some error on model or on project. These changes can be seen on the commits d2b5411, a8a1e8a and 8b2c370 .

Before I make this change on Cricket I noticed that the window interface of Toga didn't support all the parameters that a dialog of the window on toga cocoa needed, so I send a PR to adjust this (commit beeware/toga#170 ).

After the commit beeware/toga@9d9c911 the menu builder become available to be add on the Application. The menus on Cricket and each action was add on these commits : 3b8a61b, 148e6ae, 17630bf, 707431e and 2be17ea.

Each menu is compounded of:

• Python (Group.APP)
  • About Cricket (Command.section = 0)
  • Preferences (Command.section = 0)
  • Quit Cricket (Command.section = last | shortcut = CMD-Q)
• BeeWare (Group.BeeWare)
  • Open Duvet... (Command.section = 0)
• Test (Group.Test)
  • Re-run (Command.section = 0 | shortcut = CMD-A)
  • Run all (Command.section = 0 | shortcut = CMD-R)
  • Run selected (Command.section = 0 | shortcut = CMD-E)
  • Stop (Command.section = 0 | shortcut = CMD-S)
• Help (Group.HELP)
  • Open BeeWare project page (Command.section = 0)
  • Open Cricket on GitHub (Command.section = 0)
  • Open Cricket project page (Command.section = 0)
  • Open Documentation (Command.section = 0)

Apart from the sub menu Preferences , each menu was linked with their actions. The sub menu Preferences need to be discussed with @freakboy3742. Does Cricket need a configure window?

The sub menu About Cricket received a new feature in the port, when the user click on this menu item a Dialog will open with a brief detail about Cricket project.

[Dayof]

• Box

At this point, the mentor @eliasdorneles asked me how to run the application that I'm constructing, so I told him to install Cricket from my fork and run. Then, he reported an error about the package requirements, specifically the Toga package, so I add this change on the commit 085432d and e4d71d2.

I've start mapping where would be good to have the Box widget. So I drawed a temporary Cricket skeleton:

-----------------------------------------------------------
| Toolbar and Commands                                    |
-----------------------------------------------------------
| ----------------------------------------------------- | |
| |      < Split | Container >                          | |
| |              |                                      | |
| |  Option      |            Box,                      | |
| |  Container   |            Label and                 | |
| |  and         |            Text Input                | |
| |  Tree        |                                      | |
| ------------------------------------------------------- |
| |     Box, Label and Progress bar                     | |
| ------------------------------------------------------- |
| Box (Main Window content)                             | |
----------------------------------------------------------- 

The Box widget is a container for any widget, so it could contain the main content area in addition with the foot (status bar). The left side would be a mixed with the OptionContainer with the Tree of the tests. The right side, the output viewer can be inside of a box with Labels and TextInputs to show the details of each test. To hold both left and right side it be inside of a SplitContainer. On the top of the application we have the Toolbar, which can be defined on the Window widget. To interact with the system will be add some Commands on the Toolbar.

According to the above structure the basics modifications on the skeleton was made on the commits 285f1d5, b5abe93, 8c8e702 and d40ad60.

In the addition of the SplitContainer and the OptionContainer were found some errors. These errors were reported in the issues beeware/toga#167, beeware/toga#168 and beeware/toga#169. These errors will be corrected following the proposal timeline.

To continue the proposal even without dig more on those issues it was made a workaround, removing the footer for now and the outer box to not enter in conflict with the above errors. These changes was made on commit b3a1b9a.

Face of the current application.

Face of the current application with the error dialog from Toga.

The three issues reported on the beginning of this report (beeware/toga#167, beeware/toga#168 and beeware/toga#169) was fixed, then the final layout using a SplitContainer inside of a Box became into (commit 7fb008e):

[Dayof]

• Font

The current status of the Font widget on Toga allows the modification of the font family and the size of the text. On the version of Cricket that uses Tkinter there is only one font object created, the test_status (a green point on the leftmost side, if the test pass). The others labels use the default properties, that is the default font family of the system OS, (in the newest macOS versions is San Francisco) with 13 in the size attribute.

On the new version of Cricket (using Toga) it will be better let the default font for all the labels, like on the version of Tkinter, because on this way the "looks / feels like a native app for multiple platforms" will hold. For test_status it will be possible to change the size of the text to 50 but not change the weight, since this configuration its not ready on Toga yet. Also, sets a color to a Label still not possible. This complains was add as an issue (beeware/toga#175) since this should be on the final version of Cricket. This could be solved here but this task it's not critical for the GUI system works. If someone doesn't solve, it'll be solve in the end of the proposal timeline.

The commit d49ec75, I made a draft of the font for the test status. Later, when the weight and the label color be ready this draft will be complete. For now that is all I can do with a Fontwidget of Toga on Cricket.

During this widget's test, I also discovered a problem with the size of a Label, after modifying its Font size. If this Label is inside of a Box, and this Box be inside of a SplitContainer. This problem was reported on the issue beeware/toga#176.

[Dayof]

• Window

This Window core widget was add when the Application was build (precisely on the commit ac2ad43). The title of the main window was set to Cricket, the application identification to org.pybee.cricket and size of 1024x768 (according to last main window geometry of the Cricket version using Tkinter).

A toolbar was add to put the basics commands to use the Cricket GUI, like 'Stop', 'Run all', 'Run selected' and 're-run'. Also, all the inner widget will be placed inside of the main window content. Later, the window can resize if after run a test the window need to be extended according the additional information appeared. This modification was add with the PR beeware/toga#172.

This last core widget ends the Second Week Progress! (2.5 weeks)

[Dayof]

General Widgets (7.5 weeks) [OK]

Basic General Widgets (1.5 weeks)

• Button

The toolbar of the main window on the last version of the Cricket contains 4 buttons, the Stop, Run all, Run selectedand Re-run. The toolbar of the Window on Toga only allows to put Command widgets, so the adaptation of the buttons on this particular feature will be substitute for Commands widgets. The 4 basics buttons was adapt in this commit d98456a. Since the Command uses Icons instead of only Labels, I will need to find and choose icons that represent each action.

For the icons, I considered to take from the Ionicons, because is MIT licensed (100% free and open source). The following icons are those that I just downloaded and used:

The "run selected" icon I made an edition with the "play" icon to make more sense about its functionality:

I added these icons in the commits 10dc1a7 and d4c9b08.

After create the commands on the Toolbar I started adapting each method that set a configuration about their states, these changes can be seen in the commits 44e683f, 8b4e2f4 and 6f85876.

Dialogs also has buttons, in the Tkinter version of Cricket the dialogs was made from scratch, frames, labels, scroll containers and buttons, but on Toga, the Dialog widget is ready. There are 6 types of default dialogs : Info, Confirm, Question, Error, Stack Trace and Save File. The Stack Trace was chosen for Cricket errors dialogs because is possible to put a title, a message for what the errors means and the content with the errors. This change can be seen in the commit 1d6651f and 07b32b4.

Some dialogs on the last version of Cricket had their buttons text modified according to their actions, but since Toga follows the good practices from Human Interface Guidelines the labels of the buttons should be statical. So to cover which dialogs will use the retry status from the Stack Trace dialog, bellow is present a brief explanation of their usage:

• IgnorableTestLoadErrorDialog :

  • Asks for a "Continue" and a "Quit" button
  • I think since this stack trace dialog can safely be ignored, a "OK" button can be enough. If a "Cancel" button be there and its action closes the application, the user can be confused since the label isn't clear enough. The "OK" button just continues the application and if the user finds out that the errors found is really critical they can exit from the application normally.
  • Result : Stack Trace with retry = False

• TestLoadErrorDialog:

  • Asks for a "Retry" and a "Quit" button
  • The "Retry" button would allow to the application continue try to open, so I think in this case should be a critical stack trace dialog, because the user must know that one button will try to "re open" and the other will close the application. On the Human Interface Guidelines, the section about alert says : "Avoid explaining the alert buttons. If your alert text and button titles are clear, there should be no need to explain what the buttons do.", so the text of the button must be clear about what they will do.
  • Result: Stack Trace with retry = True, and instead of the default buttons "Retry" and "Cancel", should be "Retry" and "Quit".

• TestErrorsDialog:

  • Asks for a "OK" button
  • Result : Stack Trace with retry = False

• FailedTestDialog

  • Asks for a "OK" and a "Quit" button
  • This dialog it's similar to IgnorableTestLoadErrorDialog
  • Result : Stack Trace with retry = False

[Dayof]

• Switch

Switch is a native control for enabled/disabled. On Tkinter this widget is called Checkbutton. The old check box was located on the Application toolbar, but since the toolbar now only allows Command, the Switch was add on the right side of the SplitContainer, just above the tests details (image bellow). This change was made on the commit 3c75223.

[Dayof]

• Label

Some Labels was already set as a stub to the other widgets, now it's time to complete the rest of the modification. The labels for tests details was add in the commit 77f11fd. The labels on the menu items and dialogs was also set in the last topics.

The output and error forms supposed to be hidden when no test was executed and show after run the tests, this feature is not implemented yet, so I report as an issue beeware/toga#181. I sent a PR beeware/toga#184 solving this problem. The commit 1a6c504 add this modification with the feature hide and show a Box Widget .

The labels on the status bar was set on the commit 9b8f9cd.

As a workaround of the issue beeware/toga#167, the layout become as follow:

-----------------------------------------------------------
| Toolbar and Commands                                    |
-----------------------------------------------------------
| ------------------------------------------------------- | 
| |      < Split | Container Vertical >                 | |
| |              |            Switch,                   | |
| |  Option      |            Box,                      | |
| |  Container   |            Label and                 | |
| |  and         |            Text Input                | |
| |  Tree        |                                      | |
| ------------------------------------------------------- |
| |     Box, Label and Progress bar                     | |
| ------------------------------------------------------- |
| Split Container Horizontal (Main Window content)      | |
----------------------------------------------------------- 

The result of the current main window is :

With the solution of 2 split containers inside of the window, I've found another feature that could be add on SplitContainer widget, sets the initial position of the divisor (beeware/toga#186). Right now it starts on the middle.

This last basic general widget ends the Week 4 of the GSoC proposal!!

[Dayof]

Intermediate General Widgets (1 week)

• Text Input

There were 2 types of text input on the last version of Cricket, Entry and ReadOnlyText. Entry is a single line text input and ReadOnlyText is a multiline text input, so the adaptation would be TextInput and MultilineTextInput from Toga. On commit 2ba33c6 the single line input text was add and on the commit 4e1220f the input texts functionalities was update and the multiline input text add.

In the addition of the class MultilineTextInput some errors were find, the first error I created a ticket to report on Toga repository, beeware/toga#187. I also sent a PR trying to fix this error at beeware/toga#188. After this correction other issue was found, if a text is add at this input field, the frame disappears.

This issue was reported on ticket beeware/toga#194. All the text inputs was add, the result is shown on the image bellow. Some errors were found, later they have to be fixed.

The issue beeware/toga#194 was fixed and two PR was made (beeware/toga#204 and beeware/toga#206) to make the MultilineTextInput widget more alike to the TextInput. The commit 023cdd9 on Cricket was made to adapt to the PR beeware/toga#204.

The final look for both texts inputs :

[Dayof]

• Progress Bar

The current status of this widget doesn't appear at all, this issue was reported on the ticket beeware/toga#189. Even with this problem I add the widget and its functionalities on the commit c82d037 and 8fe6f11.

After beeware/toga#189 was fixed, another issue appeared, the ProgressBar doesn't show inside of a Box oriented by row using the CSS class from colosseum. This issue was also reported at beeware/toga#195. Also, another issue about the max and the value of the ProgressBar was found, the ticket is beeware/toga#196.

Even with these above errors, inside of a Boxoriented by column I was able to add all the items that supposed to be inside of the footer on the main window (image below). Commit f6cf27d.

The issues beeware/toga#195 and beeware/toga#196 were fixed, so a new commit (50b0866) was made on Cricket to adapt with the correct layout.

[Dayof]

Advance General Widgets (5.0 weeks)

• Option Container

The OptionCotainer was added at the new version of Cricket when the Box core widget was added. Although Its functionality was not updated yet. The only property that the OptionContainer should alert while the system is running is about what tab view is current selected. In the current version of Toga this feature is not implemented, so the ticket beeware/toga#197 was opened and the PR beeware/toga#198 was send to add this functionality. The usage of this feature was add on the commit 70df86e on Cricket project.

[Dayof]

• Tree

The basic usage of the Tree widget is available on Toga, but, for example, isn't possible yet change the colors of the labels inserted on the tree, show the subtree opened or closed and add tags like 'active' or 'inactive'. For now, the features available are, insert nodes on the tree and know if some node were clicked. The commit 0063cd0 add the nodes on the tree.

@freakboy3742 gave me a suggestion to add a new feature on the Tree widget to be possible to add an icon on the nodes of the tree, so I sent a PR with this feature, beeware/toga#200. This PR is a WIP that need to be rethink in the future to this addition be implemented on the nodes of the tree not on the tree itself. On the Cricket side this feature would be great to alert the user with more resources if a test had passed or fail. So I added on the commit f53d931 3 icons to implement this feature in the project, an icon to inform that a test had passed, failed or if a test is running.

The commit f8360ce, I set the wait icon when the method that runs all the tests starts. Result:

Since the Tree widget isn't completed yet, @freakboy3742 gave me instructions to refactor the widget API on Core and also on Cocoa platform. beeware/toga#200 was closed to insert this feature inside of the big refactor of this API. The PR beeware/toga#201 is open to insert the refactoring of this API.

The Tree API on Core and Cocoa platform has the features below :

• Insert headings (issue #202 remains) : https://gist.github.com/Dayof/a3928d173198acbd3e7e5341076bd630

• Insert nodes using three kinds of way :

  • Dictionary : https://gist.github.com/Dayof/3f47ea4401828326efff82775a5eb255
  • Node by node : https://gist.github.com/Dayof/44459029cbd2c0585c2c47d2bd6ed8d2
  • From a data source : https://gist.github.com/Dayof/057f7d0e7e2baf29877875d54252fc2e

• Insert icons : https://gist.github.com/Dayof/cd11e9ec0150251d392461d597e94530

• Collapse or expand : https://gist.github.com/Dayof/da991d2a641d7f67c803e386978472e6

• Bind a function to interact when nodes are selected : https://gist.github.com/Dayof/3182075a678a198565fad2f9a05d2735

The feature to change the color of a text on the Tree couldn't be implemented on Cocoa platform. The NSBrowserCell class enables to add an image and a text inside of a cell on the NSTableColumn that is used to represent the Tree structure, but it not allows to set the color of the text, the default cell NSCell of NSTableColumn allow to modify the color but can't add image within the cell. @freakboy3742 recommended to give preference to add the icon instead of the color.

The Toga data source API was add on Cricket in the commit f374ce6, 50af4f2 and 3edfbd9.

After the adaptation of the data source api of toga.Tree in Cricket, some features was fixed so the project could run the tests normally. These modifications was made on the commits be55a29, 24ae477, 3d1a4b6 and 6c82987.

The feature to run multiple selected tests was implemented on Cricket in the commit 1dc0a98. Before implemented this feature on toga.Tree api, I encountered a challenge to interact with NSIndexSet as an iterable object. The first idea to make this possible was to use block notation from Objective C using the lib rubicon-objc to implement this syntax in python, but I discovered that this feature is a WIP and I sent an issue (ojii/rubicon-objc#1) to help develop this notation on rubicon-objc. Then, I made a workaround to interact with the elements from the NSIndexSet because the block notation wasn't ready.

Set icons using the Toga data source api according to the status after run a test method was add in this commit c52c07d on Cricket.

The problem tree was set in the commit 6989ee4 on Cricket.

[Dayof]

Layout Widgets (0 week) [OK]

• Scroll Container

Scroll containers was used on dialogs, but indirectly when Window was built. The basic layout uses boxes instead of Scroll Containers.

• Split Container

The main content of the application use SplitContainer. This widget was added when the Box widget was being add on the application, more detail about this widget is explained above.

Usage documentation -- last milestone (2 weeks) [OK]

Some example codes was made when a PR was sent or a issue was created. Button and Tree widgets received more attention on this:

• Button example code merged on the PR [Cocoa] Button example on docs folder  toga#174
• Tree api examples code inside of the discussion of the PR Refactoring of the Tree widget [Core][Cocoa] [WIP] toga#201

Final considerations

Finally the end of the proposal arrived! After this migration from Tkinter to Toga almost all features was covered. There are still some work to complete on Cricket, for example:

• Fix a gap between output box and error box if there is no output message
• Run a test if the user click on it
• Create a button to refresh all the tests tree
• Settings menu

Here is the final demonstration of the current version of Cricket : https://youtu.be/5kz_CmQYFYE.

😄 ✌️