2 * Copyright (C) 2016 - 2022 Free Software Foundation
4 * This program is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation, either version 3 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program. If not, see <http://www.gnu.org/licenses/>.
17 package org.mxchange.addressbook.client;
19 import org.mxchange.addressbook.menu.item.SelectableMenuItem;
20 import org.mxchange.jcontacts.model.contact.Contact;
21 import org.mxchange.jcontacts.model.contact.title.PersonalTitle;
22 import org.mxchange.jcore.client.Client;
23 import org.mxchange.jcore.exceptions.MenuInitializationException;
24 import org.mxchange.jcore.exceptions.UnhandledUserChoiceException;
27 * A special client interface for addressbook applications.
29 * @author Roland Häder<roland@mxchange.org>
31 public interface AddressbookClient extends Client {
34 * Displays a "box" for the address
36 * @param contact Contact to show address from
38 void displayAddressBox (final Contact contact);
41 * Displays a "box" for the name
43 * @param contact Contact to show name from
45 void displayNameBox (final Contact contact);
48 * Displays a "box" for other data
50 * @param contact Contact to show other data from
52 void displayOtherDataBox (final Contact contact);
55 * Shows given contact instamce
57 * @param contact Contact instance
59 void show (final Contact contact);
62 * The user changes own address data
64 * @param contact Contact instance to change
66 void doChangeOwnAddressData (final Contact contact);
69 * The user changes own name data
73 void doChangeOwnNameData (final Contact contact);
76 * The user changes own other data
78 * @param contact Constact instance to change
80 void doChangeOwnOtherData (final Contact contact);
83 * Allows the user to enter own data
85 * @return Finished Contact instance
87 Contact doEnterOwnData ();
90 * Asks the user for a choice and proceeds accordingly
92 * @throws UnhandledUserChoiceException If choice is not supported
93 * @throws org.mxchange.jcore.exceptions.MenuInitializationException If the
94 * menu cannot be initialized
96 void doUserMenuChoice () throws UnhandledUserChoiceException, MenuInitializationException;
99 * Asks the the user to enter a single character which must match validChars
101 * @param validChars Valid chars that are accepted
102 * @param message Message to user
104 * @return Allowed character
106 char enterChar (final char[] validChars, final String message);
109 * Asks the user to enter his/her personal title (M=Male, F=Female,
112 * @param message Message to output
114 * @return PersonalTitle enum
116 PersonalTitle enterPersonalTitle (final String message);
119 * Reads an integer (int) from the user
121 * @param minimum Minimum allowed number
122 * @param maximum Maximum allowed number
123 * @param message Message to user
125 * @return Entered string by user or null if empty string is allowed
127 int enterInt (final int minimum, final int maximum, final String message);
130 * Reads a string of minimum and maximum length from the user. An empty
131 * string should be generally not allowed, but might be okay for e.g.
134 * @param minLength Minimum length of the string to read
135 * @param maxLength Maximum length of the string to read
136 * @param message Message to user
137 * @param allowEmpty Whether empty strings are allowed
139 * @return Entered string by user or null if empty string is allowed
141 String enterString (final int minLength, final int maxLength, final String message, final boolean allowEmpty);
144 * Setter for current menu choice
146 * @param currentMenu Current menu choice
148 void setCurrentMenu (final String currentMenu);
151 * Some "Getter" for menu item
153 * @param accessKey Key to press to access this menu
154 * @param text Text to show to user
158 SelectableMenuItem getMenuItem (final char accessKey, final String text);
161 * Shows current menu selection to the user
163 void showCurrentMenu ();
166 * Shows given menu entry in client
168 * @param item Menu item to show
170 void showEntry (final SelectableMenuItem item);
173 * Let the user choose what to change on the address: [n]ame, [a]ddress,
176 * @param contact Contact instance to let the user change data
178 * @throws UnhandledUserChoiceException If choice is not supported
180 void userChooseChangeContactData (final Contact contact) throws UnhandledUserChoiceException;