From 0ddaea9b5c708c21a88fc35268073905dfd200a8 Mon Sep 17 00:00:00 2001 From: IndrekV Date: Mon, 19 Nov 2018 07:44:17 +0200 Subject: [PATCH] Added mac documentation --- docs/mac/autocompletion.md | 31 ++++++++++++++++++++++++++ docs/mac/edit-popup.md | 30 +++++++++++++++++++++++++ docs/mac/index.md | 18 +++++++++++++++ docs/mac/main-window.md | 45 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 124 insertions(+) create mode 100644 docs/mac/autocompletion.md create mode 100644 docs/mac/edit-popup.md create mode 100644 docs/mac/index.md create mode 100644 docs/mac/main-window.md diff --git a/docs/mac/autocompletion.md b/docs/mac/autocompletion.md new file mode 100644 index 0000000000..84e81f4156 --- /dev/null +++ b/docs/mac/autocompletion.md @@ -0,0 +1,31 @@ + +# Autocompletion + +To handle the context specific requirements of inputting data into Toggl, the Windows UI of Toggl Desktop includes an entirely custom system to handle autocompletion and suggestions of user input. + +This system is used all across the application's edit view as well as in the timer, to help the user quickly complete their input. + +Autocomplete system consists of the following components: + +## AutoCompleteInput + +This is the item element. It tracks keyboard events and shows/hides autocomplete suggestions dropdown table. + +## AutoCompleteTable + +Keeps track of the currently highlighted / selected item. Handles mouse events on table items. + +## AutoCompleteTableCell + +Handles data display on cell view item. All font colors sizes an styles are attached here. + +## LiteAutoCompleteDataSoure + +This is where all the data is handled: +- Filling in data to the table +- Creating categories and groups +- Filtering table items based on the typed in text + +## AutoComopleteTableContainer + +Simple Table container for the AutoCompleteTable view. diff --git a/docs/mac/edit-popup.md b/docs/mac/edit-popup.md new file mode 100644 index 0000000000..83532be1d5 --- /dev/null +++ b/docs/mac/edit-popup.md @@ -0,0 +1,30 @@ + +# Edit popup + +This file documents the edit popup and edit view of the Mac UI of Toggl Desktop. + +The edit popup is a major part of the application since its single view is the primary way of entering and changing details of time entries. + +The implementation can be found in `TimeEntryEditViewController.*`. + + +## Edit popup window + +The edit view popup window is a popover connected to the TimeEntryList. It is so because when connecting to certain time entry inside the list, the connection would be broken when list refreshes while edit popup is opened. + +It opens and closes with an animation and can be resized horizontally. + + +## Edit view + +The edit view is a complex control containing input fields for changing all aspects of a time entry. + +The view also contains functionality to add clients and projects. + +Most of the input fields of the view are linked to auto completion lists provided by the library. These are: the description, project, client, workspace, and tags. + +Description and project autocomplete is a custom component with grouping and colorful texts. Other items use regular built in comboboxes with datasources that work as autocompletes. + +Care is taken to not override the data in the field a user is editing at the time. + +All data is saved as user moves away from the field. The exception is adding new project. If new project is created it will be created and attached to the entry when the popup closes. \ No newline at end of file diff --git a/docs/mac/index.md b/docs/mac/index.md new file mode 100644 index 0000000000..43f05e99d0 --- /dev/null +++ b/docs/mac/index.md @@ -0,0 +1,18 @@ + +# Toggl Desktop Mac UI Documentation + +These files document the general structure and architecture of the Mac UI of Toggl Desktop and its main components. + +The total application is composed of two major parts: The interface, written in Objective-C and the library containing most business logic. This documentation deals only with the interface, and the API as used by it. + +## Table of contents + +- Main UI parts + - [Main window](main-window.md) + - [Login view](main-window.md#login-view) + - [Time entry list view](main-window.md#time-entry-list-view) + - [Timer](main-window.md#timer) + - [Time entry list](main-window.md#time-entry-list) + - [Edit popup](edit-popup.md) + - [Edit view](edit-popup.md#edit-view) + - [Autocompletion](autocompletion.md) \ No newline at end of file diff --git a/docs/mac/main-window.md b/docs/mac/main-window.md new file mode 100644 index 0000000000..712bb7d209 --- /dev/null +++ b/docs/mac/main-window.md @@ -0,0 +1,45 @@ + +# Main window + +This file documents the main window of the Mac UI of Toggl Desktop. + +## Main window views + +All views are initialize in the `- (id)initWithWindow:(NSWindow *)window` method of the window. + +Views are displayed/hidden by simply adding or removing them as subviews. + +There are 3 different views: LoginView, TimeEntryListView and OverlayView; + +### Login view + +The login view handles both logging in, and signing up for a new Toggl account. + +The implementation can be found in `LoginViewController.*`. + +In addition, the login view also contains the code to initialise a login using Google OAuth. When Google login is chosen it opens up in-app browser window and allows user to log in to Google. + +### Time entry list view + +The time entry list view is the central part of the UI. It includes both the timer, and the list of time entries. The view also handles opening and closing a popover with time entry details for editing. + +The implementation can be found in `TimeEntryListViewController.*`. + + +#### Timer + +The timer provides the functionality to start and stop tracking. + +Its implementation can be found in `TimerEditViewControler.*`. + +When stopped (not tracking) the timer allows the user to input descriptions, as well as select projects through an auto completing text box. It also allows to start the timer with the given info using the start button. + +When running, the timer displays the time entries information, including the current running time. The user can stop tracking using the stop button, or open the edit popup to edit the running time entry, by clicking on the displayed information in the running timer. + +#### Time entry list + +The time entry list contains the list of past time entries. + +Its implementation can be found in `NSUnstripedTableView.*` inside `TimeEntryListViewController`. + +The `NSUnstripedTableView` handles entry deletion, keyboard shortcuts and getting selected item in the list. All the list loading and editing popup triggering is done in `TimeEntryListViewController`. \ No newline at end of file