Merge branch 'subtree'
[fanfix.git] / docs / android / android.md
CommitLineData
bac39c50
NR
1# Android UI mock-up
2
3## Concepts
4
5### Story
6
7We have **Stories** in Fanfix, which represent a story (an "epub", ...) or a comics (a "CBZ" file, ...).
8
9A story is written by an author, comes from a source and is dentified by a LUID (Local Unique ID).
10It can be a text story or an image story.
11
12The source can actually be changed by the user (this is the main sorting key).
13
14### Book
15
16We also have **Books**.
17
18Books can be used to display:
19
20- All the sources present in the library
21- All the authors known in the lbrary
22- Stories sharing a source or an author
23
24### All and Listing modes
25
26When representing sources or authors, books can be arranged in two modes:
27
28- "All" mode : all the sources/authors are represented by a book and displayed in the UI
29- "Listing" mode : for each source/author, a group of books representing the corresponding story is present with the name of the source/author to group them (for instance, a JLabel on top of the group)
30
31Note: Listing mode can be left out of the Android version if needed (but the all mode is really needed).
32
33### Destination
34
35What I call here a destination is a specific group of books.
36
37Examples :
38
39- All the sources
40- All the books of author "Tulipe, F."
41- A listing of all the authors and their stories
42
43## Core
44
45### Library (main screen)
46
ea5b1120 47![Main library](screens/main_lib.jpg)
bac39c50
NR
48
49#### Header
50
51The header has a title, a navigation icon on the left and a search icon.
52
53Title can vary upon the current displayed books:
54
55- All sources
56- Sources listing
57- Source: xxx
58- All authors
59- Authors listing
60- Author: xxx
61
62The navigation icon open the Navigation drawer.
63
ea5b1120
NR
64##### Search
65
66![Search/Filter](screens/search.jpg)
67
bac39c50
NR
68The search icon is actually a filter: it will hide all the books that don't contain the given text (search on LUID, title and author).
69
70#### List
71
72This list will hold books. Each item will be represented by :
73
74- a cover image (which is provided by fanfix.jar)
75- a main info, which can be:
76 - for stories, the story title
77 - for source books, the source name
78 - for author books, the author name
79- a secondary info, which can vary via a setting (see the Options page) between:
80 - author name (for a book representing an author, it is left blank)
81 - a count (a word count for text stories, an image count for images stories, a stories count for sources and authors books)
82
83#### UI
84
85Material.IO:
86
f54ad2cb
N
87- Title, navigation icon, search icon : [App bar top](https://material.io/design/components/app-bars-top.html)
88- List : [Cards](https://material.io/design/components/cards.html)
bac39c50 89
f54ad2cb 90A tap will open the target book in full-screen mode (i.e., the details about the card).
bac39c50 91
f54ad2cb
N
92On the detailed card, you will see the description (see Description Page) and 3 buttons :
93
94- Open
95- Delete
96- "..." for a menu
bac39c50
NR
97
98### Navigation drawer
99
ea5b1120 100![Navigation Drawer](screens/navigation.jpg)
bac39c50
NR
101
102The navigation drawer will list 4 destinations:
103
104- All the sources
105- Listing of the sources
106- All the authors
107- Listing of the authors
108- By source
109
110...and 2 foldable "panels" with more destinations:
111
112- By source
113- By author
114
115Those subpanels will either contain the sources/authors **or** sub-subpanels with sources/authors.
116See fanfix.jar (BasicLibrary.getSourcesGrouped() and BasicLibrary.getAuthorsGrouped()).
117
6d5f99c7
NR
118Note: if those last two cause problems, they can be removed; the first four options would be enough to cover the main use cases.
119
bac39c50
NR
120#### UI
121
122Material.IO:
123
124- Navigation drawer: navigation drawer
125
bac39c50
NR
126### Context menu
127
ea5b1120 128![Context Menu](screens/menu.jpg)
bac39c50
NR
129
130The context menu options are as follow for stories:
131
132- Open : open the book (= internal or external reader)
133- Rename... : ask the user for a new title for the story (default is current name)
134- Move to >> : show a "new source..." option as well as the current ones fo quick select (BasicLibrary.getSourcesGrouped() will return all the sources on only one level if their number is small enough)
135 - *
136 - [new source...]
137 - [A-H]
138 - Anima
139 - Fanfiction.NET
140 - [I-Z]
141 - MangaFox
142- Change author to >> : show a "new author..." option as well as the current ones fo quick select (BasicLibrary.getAuthorsGrouped() will return all the authors on only one level if their number is small enough)
143 - *
144 - [new author...]
145 - [0-9]
146 - 5-stars
147 - [A-H]
148 - Albert
149 - BĂ©atrice
150 - Hakan
151 - [I-Z]
152 - Irma
153 - Zoul
154- Delete : delete the story
155- Redownload : redownload the story (will **not** delete the original)
156- Properties : open the properties page
157
158For other books (sources and authors):
159
160- Open: open the book (= go to the selected destination)
161
162#### UI
163
164Material.IO:
165
f54ad2cb
N
166- menu: [menu](https://developer.android.com/guide/topics/ui/menus.html)
167
168The menu will NOT use sublevels but link to a [list](https://material.io/design/components/lists.html) instead.
bac39c50
NR
169
170### Description page
171
ea5b1120 172![Description Page](screens/desc.jpg)
bac39c50
NR
173
174#### Header
175
8c8419c8 176Use the same cover image as the books, and the description key/values comes from BasicReader.getMetaDesc(MetaData).
bac39c50
NR
177
178#### Description
179
180Simply display Story.getMeta().getResume(), without adding the chapter number (it is always 0 for description).
181
182An example can be seen in be.nikiroo.fanfix.ui.GuiReaderViewerTextOutput.java.
183
184### Options page
185
ea5b1120
NR
186![Options Page](screens/options.jpg)
187
bac39c50
NR
188It consists of a "Remote Library" panel:
189
190- enable : an option to enable/disable the remote library (if disabled, use the local library instead)
191- server : (only enabled if the remote library is) the remote server host
192- port : (only enabled if the remote library is) the remote server port
193- key : (only enabled if the remote library is) the remote server secret key
194
195...and 5 other options:
196
197- Open CBZ files internally : open CBZ files with the internal viewer
198- Open epub files internally : open EPUB files with the internal viewer
199- Show handles on image viewer : can hide the handles used as cues in the image viewer to know where to click
200- Startup screen : select the destination to show on application startup
201- Language : select the language to use
202
203#### Startup screen
204
205Can be:
206
207- Sources
208 - All
209 - Listing
210- Authors
211 - All
212 - Listing
213
214...but will have to be presented in a better way to the user (i.e., better names).
215
216#### UI
217
218Material.IO:
219
220- the page itself : Temporary UI Region
221- the options : Switch
222- the languages : Exposed Dropdown Menu
223- the text fields : the default for text fields
b19b9ba2 224- the scret key field : the default for passwords (with * * * )
bac39c50 225
b19b9ba2
NR
226## Internal viewer
227
228The program will have an internal viewer that will be able to display the 2 kinds of stories (images and text).
229
230### Base viewer
231
232This is common to both of the viewer (this is **not** an architectural directives, I only speak about the concept here).
233
ea5b1120 234![Base Viewer](screens/viewer.jpg)
b19b9ba2
NR
235
236#### Header
237
238The title is the title of the story, shortened with "..." if too long.
239
240#### Content
241
242This area will host the text viewer or the image viewer.
243
244#### Navigator
245
246It contains 4 action buttons (first, previous, next and last chapter) and the title of the current chapter:
247
248- Descripton : for the properties page (same layout as the actual Properties page)
249- Chapter X/Y: title : for the normal chapters (note that "Chapter X/Y" should be bold, and "X" should be coloured)
250
251#### UI
252
253Matrial.IO:
254
255- Header : Header
f54ad2cb 256- Navigator : [Sheets bottom](https://material.io/design/components/sheets-bottom.html)
b19b9ba2
NR
257
258### Text viewer
259
ea5b1120 260![Text Viewer](screens/viewer-text.jpg)
b19b9ba2
NR
261
262It will contain the content of the current chapter (Story.getChapters().get(index - 1)).
263
264Same layout as the Properties page uses for the resume, with just a small difference: the chapter name is now prefixed by "Chaper X: ".
265
266### Image viewer
267
ea5b1120 268![Image Viewer](screens/viewer-image.jpg)
b19b9ba2
NR
269
270#### Image
271
272Auto-zoom and fit (keep aspect ratio).
273
274#### Image counter
275
276Just display "Image X/Y"
277
278#### Handles
279
280This is a simple cue to show the user where to click.
281
282It can be hidden via the option "Show handles on image viewer" from the Options page.
283
284#### UI
285
286Pinch & Zoom should be allowed.
287
288Drag-to-pan should be allowed.
bac39c50 289