User Interface Specification:
Task List integration

Author: Dusan Pavlica, Gabriel Tichy
Last Updated: January 9, 2004
Version: Final version

Table of Contents

• Introduction
• References
• Detailed Spec
  • Invocation and behavior of To Do window
  • Look of the To Do Window
  • Icons and ToolBar of To Do window
  • Shortcuts for the To Do
  • Switching between tasks in Current File or tasks in Selected Folder
  • Progress indication about searching tasks
  • Concept of task filtering
  • Dialog of Filters
  • Options for To Do
  • Contextual menu in the To Do window
  • Other design issues
  • Enhancements
• Open Issues

---

Introduction

This feature is about integration of existing Task list to official distribution. The task list project consists of multiple submodules contributed by various people and we will use only basic and stable functionality (only submodules core, api, editor, suggestions, docscan). The rest remains on beta autoupdate. We realized, that first version will include only scanning of code (e.g. TODO, HACK, FIXME, etc.) for Current File opened in Source Editor, All Opened Files in the Editor and for Selected Folder in Filesystems (Project). Many of other functionality (Suggestions, User Task..) will be removed temporarily.

 

References

• Main Page about old Task List implementation: http://tasklist.netbeans.org/
• Use case description: http://tasklist.netbeans.org/proposals/barracuda/concept.html
• Functional Specification: http://tasklist.netbeans.org/proposals/barracuda/func-spec.html
• Design specification: http://tasklist.netbeans.org/proposals/barracuda/design-spec.html
• Another usage of UI concept with toggle buttons: http://ui.netbeans.org/docs/ui/palette/newUI.html

 

Detailed Spec

Main change as opposed to old version of Task List source scanning is its Toolbar and concept of switching between Current File view, Opened Files view and Selected Folder view.
Scanning many files in Filesystems could take an age, so clear indication about it and possibility to stop this prolonged scanning is necessary too.

Invocation and behavior of To Do window

User could invoke To Do from To Do menu Item in Main Menu or from Window ToolBar and following actions will be performed:

• To Do window will appear at the same place like the Output area (for example).
• It will activate Current File toggle button by default and all tasks from current file which is opened in Editor will appear immediately.
• User could switch on Opened Files toggle button and it will start to search for tasks through all opened files in the Editor immediately. This result of searching will be kept actual still in the background (note: this feature won't be in release 3.6).
• User could switch on Selected Folder toggle button and it will open standard File Chooser for the first time.When folder is chosen, searching through Selected Folder will start immediately. Each selected folder is stored into history of folders (see section about popup menu of selected folders).
• Progress indication about this action will appear on right side of a Toolbar situated in Task List window. This indication includes label (Searching for tasks:), Progress Bar and Stop button.
• Tasks should be filed into To Do list incrementally during scan action which could be stopped by Stop button.
• When limit of searched tasks is exceeded, then message about it will appear in the status line of To Do window. This limit could be changed in the Options (see below in a section about Options)
• Each next switching to the Selected Folder view will display cached list of tasks. User could refresh it by Refresh button situated in the ToolBar or could define another folder using arrow button attached to Selected Folder button. This arrow will invoke popup menu with history of folders and Choose Folder... Menu Item for invocation of File Chooser.
• When user selects different folder which isn't in history, new searching will start once again. Results of each searching could be cached ideally, but there is a problem with performance and memory usage. So we don't recommend this caching for each folder, only for last one.

Look of the To Do Window

This look is specified for Windows 2000 L&F and new concept of ToolBar toggle buttons is used there.
Standard ToolBars toggle buttons will be used for others supported L&F. More about this issue is on this address (here will exist link to specification about consistency of Toggle buttons).

 

 

Below are visible phases of the proposed solution with Selected Folder toggle button and attached down arrow symbol.
This arrow will invoke popup menu including history of selected folders and possibility to choose a new one.

figure 1: Current File view

figure 2: Current File view and mouse is over Selected Folder toggle button

figure 3: Selected Folder view and Selected Folder toggle button is pressed

figure 4: Selected Folder view with pressed Selected Folder toggle button and mouse is over arrow button

figure 5: Selected Folder view, pressed Selected Folder toggle button and popup menu was invoked by clicking on arrow button

figure 6: Searching for tasks through all files in the Selected Folder. Tasks are added in to the To Do list incrementally

figure 7: Selected Folder view and Searching for tasks finished

figure 8: Selected Folder view with popup menu of Filters

figure 9: Selected Folder view with active Filter

 

Icons and ToolBar of To Do window

• Main Menu - To Do  Ctrl+8 menu item exist in Windows Menu and its action will invoke To Do window.
• Main ToolBar - Icon of To Do window could exist in Window ToolBar too, but context of this ToolBar isn't defined very well at all.
• ToolBar - I contains following three parts:
  1. Toggle buttons part - Three buttons for switching among Current File (c) view, Opened Files (o) view and Selected Folder (s) view are situated there. Last one is combined with another arrow button (S).
  2. Action Icons part -  It contains three icons:
     • Show selected task in the Editor (e) - It will open Source in the Source Editor at exact position of task (TODO, HACK, FIXME etc.).
     • Refresh list of tasks (r) - User could run again that search action by Refresh icon in Task List's ToolBar every time.
     • Define filter for tasks (f) - It will invoke a popup menu with actions related to filtering.
     • Next possible icons but not for release 3.6: Show Next Tasks in the Editor (F12) and Show previous tasks in the Editor (Shift+F12)
  3. Status part - It could be empty (fig.1), could contain information about active Filtered View (fig.9) or Progress indication about searching through Selected Folder could be placed there (fig.6). When more texts should be displayed at once, then these texts should be displayed in following order with comma among them:
     Filtered View, Selected Folder: a_name_of_the_selected_folder, Showing only first XY tasks.

 

Shortcuts for the To Do

All shortcuts are visible by each action of icons mentioned above. Additionally shortcut for three toggle buttons are defined:

• Current File toggle button - Switches for tasks in currently edited file - shortcut "c"
• Opened Files toggle button - Switches for tasks in all opened files - shortcut "o"
• Selected Folder toggle button - Switches for tasks in all files in selected folder - shortcut "s"
• Arrow button attached to Selected Folder button - Selects folder for scanning - shortcut "S"

 

Switching between tasks in Current File or tasks in Selected Folder

This action could be frequented and accessible easily. And that's why we use toggle buttons for supporting it.
When user invokes To Do window for the first time, Current File view appears by default and tasks are added into the To Do list view immediately.
When user switches to the Selected Folder view for the first time, then dialog for selection of folder will appear.
When user switches to the Selected Folder view for the next times, then cached results of tasks from previous searching will appear in the To Do list.
Searching for tasks starts after each selection of folder immediately with Progress indication about process.
User could define a new folder easily by Arrow button attached to Selected Folder toggle button.
User could use Refresh action from ToolBar always for a restart of To Do list.

 

Progress indication about searching tasks

Searching tasks through the Selected Folder could take too much time (sometimes more then 10s) and that's why clear progress indication should be visible.
We haven't Global Progress indicator, then we use local progress indication, which displays on demand in ToolBar of To Do window. It has three parts:

• Label - Static label with title "Searching for tasks:"
• Progress status bar - Non-deterministic status bar is useable for this, but better way is to use Deterministic status bar with text about percentage (and about amount of files) situated inside.
• Stop button - User could interrupt searching by "Stop" button and all present tasks will remains in To Do list.

When searching of task is in progress or ends, then result will appear in the header of result table in this format: XY tasks in folder: name_of_the_selected_folder
But there is problem with implementation of this text in the header of list. So it will be displayed (only temporarily and should be fixed in the future) in the local status line in following format: Selected Folder: name_of_the_selected_folder
When limit of searched tasks is exceeded, then following message will appear in the local status line: Showing only first XY tasks.
This label could has assigned following ToolTip: You can change limit of tasks displayed in the Options window under To Do Settings folder.

 

Concept of task filtering

When big amount of tasks exist in To Do list, then concept of filtering is needed. We defined these three actions, where first and second are radio menu items:

• (  ) Filter Activated - This popup menu action activates defined filter. If no-one filter is set then Filter dialog is invoked.
• (o) Filter Deactivated - (checked by default) This action deactivates used filter, but all conditions will remain in Filter dialog.
•      Edit Filter... - It invokes Filter dialog, where user could defined one or more conditions for filtering. When any filter is defined, then label Filtered View will appear in local status line of To Do window.

These actions could be invoked through Filter icon in the ToolBar of To Do. When user click on it, then following popup menu will appear:

Dialog of Filters

It will be changed from an old design into following design:

Properties of the Dialog:

1. Match All of the Following - l has mnemonic
2. Match Any of the Following - y has mnemonic
3. List of Filters - filters are aligned to the top.
4. More button - M has mnemonic
5. Fewer button - F has mnemonic

 

Options for To Do

Options will be changed in this way:

Options>Editing> To Do Settings contains following setting:

• Skip Tasks Outside Comments: CheckBox
• Task Tags: List of tags with priority. It's customizable by Customize Button. Then following dialog will appears:
  
  
  
  Dialog contains Table with two columns (Name, Priority) and three buttons (Add, Edit, Remove).
  Add and Edit buttons invoke special dialog with following elements inside:
  • TextField for define new/change old name of tag
  • ComboBox for define new/change old priority for tag
  • OK and Cancel buttons
• To Do List Limit: number. Default value is 500 and maximal value is 1000.

Source Scan Framework is the new name for Suggestions Framework option and right place for it should be solved besides. There are two possibilities:

• Options>Editing>Source Scan Framework
• Options>IE Configuration>System>Source Scan Framework
  

 

Contextual menu in the To Do window

A. When user click on empty area in TreeTable view:

• List Options with subitems typical for Tree Table component (Sort, Change visible columns)

B. When user clicks on some task node:

• Show Source - It will open Source in the Source Editor at exact position of task (TODO, HACK, FIXME etc.).
• Properties - It will open Properties with all details about selected task
• --------------------
• List Options - The same like in the case A

 

Other design issues

• No Icons won't be displayed in Margin of Source Editor. Currently Suggestion and User Tasks are there and should be removed. When concept of icons in Margin will be improved, then we could have clickable To Do icon there and it will invoke To Do window.
• Height of list cells should be 1 pixel bigger then in old implementation of the Task List.
• New design contains different four columns by default (Tasks, Priority, Filename, Line).

 

Enhancements

To Do behavior and look could be improved more in the future and here are some possible improvements:

• We can add Opened Files toggle button and provide a live scanning for all opened files in the Editor.
• To Do window could be invoke-able from Contextual menu of the Filesystems window. Then it could be opened with the Current File view or the Selected Folder View. In the second case searching for tasks will start immediately and the folder will be added into the history of folders.
• We could add these two icons with appropriate actions to the local ToolBar of To Do window: Show Next Tasks in the Editor (F12) and Show previous tasks in the Editor (Shift+F12).
• To Do window could be invoked from Margin of the Editor, but click-able concept of Margin should be changed a bit.
• Filter button could be changed for toggle button with attached arrow and its behavior will be the same like for Selected Folder toggle button. It will invoke popup menu with history of filters (5 is maximum) and Edit Filter... menu item. Then Filtered View label from the local status line will be removed and UI concept of To Do window will be more clear in this way:
  

  Filtered View and Filter is activated		Filtered View with mouse over filter icon or arrow icon

   

• Idea about another enhancement with minimization of Toolbars I took from Mozzila. It's about intelligent dragger on the left side of Toolbar. It has these two states:
  • expanded - Small drag texture in a vertical position is on the left side and ToolBar is visible.
  • collapsed - Small drag texture in a horizontal position is on the left side and ToolBar isn't visible.
    
• Cooperation with suggestion framework is big area for improvement too. E.g. auto-generation of //XXX comments into code is one part of it.

 

 

Open Issues

• Design of internal TABs should be consistent through all IDE
• We changed name for this module from Task List to To Do name (after competitive check and because User tasks, which remaining at the Update Center). We should change name of module in the source code and trunk too maybe.
• What's about discoverability of possible tags for searching. That list is in the Options under To Do settings node, but could we allow to invoke it from To Do list window too ?