<<<<<<< HEAD
RoboJournal Documentation

for version 0.4.2

RoboJournal Fundamentals

Sections

FYI: Toolbar button labels have been disabled in every screenshot of the main window used in this documentation to ensure that all buttons are fully visible for demonstration purposes.
  1. Default State
  2. Main Window Anatomy
  3. Making a Connection
  4. Disconnecting
  5. Writing a New Entry
  6. Modifying an Existing Entry
  7. Deleting an Entry
  8. Navigating the Chronological Entry List
  9. Tagging an Entry
  10. Exporting an Entry
  11. Searching for an Entry

Default State

RoboJournal is ready for regular day-to-day use once it has been properly configured through first-run mode. When RoboJournal is started under normal conditions, the main window is displayed:

RoboJournal Main Window in Default StateFigure 1: RoboJournal's main window in "Default State".

The initial configuration of the main window (immediately after starting the program) is known as the "Default State" in this documentation. Most of the main window's functionality (except Connect and RoboJournal Preferences) is locked while the program is in the Default State because the locked functions specifically affect the current journal; in other words, there is nothing for these functions to do without an active connection. Therefore, you must make a connection to unlock this functionality.

Main Window Anatomy

On a superficial level, RoboJournal's main window consists of two large areas bifurcated by a movable splitter object. The Chronological Entry List (Item 12 in Figure 2) is always located on the left side of the splitter while the Entry Output Pane (Item 18) is always on the right. The rest of the window contains a movable toolbar, a status bar, and the standard drop-down File, Edit, etc. menus common to most Windows programs.

RoboJournal's toolbar can be docked on the left, right, or top margin of the main window. The toolbar cannot be free-floated or discarded (although it can be temporarily hidden by selecting the appropriate option in the Show sub-menu on the Window drop-down menu). You can change the location of the toolbar by dragging the toolbar docking widget to the position where you want the toolbar to be or by selecting the desired position from the Toolbar position sub-menu on the Window drop-down menu. For ease of identification, the toolbar docking widget is always on the far left side of the toolbar or on the very top if the toolbar is currently docked vertically (the docking widget's appearance may vary by operating system). Your mouse pointer changes to a four-directional arrow while it is hovering over the toolbar docking widget. The layout automatically adjusts once the toolbar has been moved to a new location. Be advised that moving the toolbar this way is temporary; the only way to permanently change the toolbar orientation is by selecting a different default position in RoboJournal Preferences.

The splitter object separates the Chronological Entry List from the Entry Output Pane and determines how much window space is allocated to each. By default, the splitter divides the RoboJournal main window roughly in half on the vertical axis, regardless of window size. If desired, you can drag the splitter bar left or right to shrink or grow the sizes of the Chronological Entry List and the Entry Output Pane. Moving the splitter all the way left or all the way right collapses the object on that side, rendering it invisible. The remaining object expands to fill the entire horizontal axis of the window. If you move the splitter bar to a new location, RoboJournal saves the coordinates and automatically applies them to future sessions. RoboJournal reverts the splitter to the default position if the saved coordinate data becomes unavailable for some reason.

The following diagram and table provide a complete explanation of each element in the main window layout. Each numbered item in Figure 2 corresponds to the table row bearing the same number:

Figure 2Figure 2: RoboJournal main window elements identified by number (the toolbar has been docked to the left for more convenient numbering).


1. Connect toolbar button — Establishes a connection to a journal database.
2. Disconnect toolbar button — Terminates the current connection.
3. Latest toolbar button — Causes RoboJournal to jump to the most recent entry in the Chronological Entry List.
4. Previous Entry toolbar button — Displays the entry immediately before the currently-selected item in the Chronological Entry List (if possible).
5. Next Entry toolbar button — Displays the entry immediately after the currently-selected item in the Chronological Entry List (if possible).
6. Manage Tags toolbar button — Launches the Manage Tags dialog (affecting the currently-selected entry in the Chronological Entry List).
7. Export Content toolbar button — Displays the Entry Exporter dialog (affecting the currently-selected entry in the Chronological Entry List).
8. Write in Journal toolbar button — Launches the Editor dialog in "Write" (new entry) mode.
9. Modify Entry toolbar button — Launches the Editor dialog in "Edit" mode (affecting the currently-selected entry in the Chronological Entry List).
10. Delete Entry toolbar button— Deletes the currently-selected entry in the Chronological Entry List.
11. RoboJournal Preferences toolbar button — Displays the RoboJournal Preferences dialog.
12. Chronological Entry List — Displays entries (in the current range) from the current journal in chronological order from newest to oldest using a hierarchical tree format. Entries are usually grouped by the year and month in which they were created.
13. Entries tab — Clicking this tab causes RoboJournal to display the Chronological Entry List on the left side of the main window splitter.
14. Connection Indicator — This text provides information about the current connection (i.e. the database type, the database name, and the host on which the database is located).
15. Search tab — Displays the search interface in the place of the Chronological Entry List on the left side of the main window splitter.
16. Username Indicator — This field displays the username of the active user. The avatar icon located to the left of the name switches depending on the user's gender.
17. Entry Count/Entry Range Indicator — The Entry Count displays the number of entries in the current journal OR the number of entries in the allotted range (if a year range has been set in RoboJournal Preferences). The Entry Count displays the total number of entries in the journal if there is no entry range set.

The Entry Range Indicator is displayed if an entry limit has been set and you have decided to display the entry range indicator. For instance, Entry Count WITH Range Indicator means that RoboJournal is displaying six entries made over the course of two years.

18. Entry Output Pane — This large area is used to display the currently-selected entry in the Chronological Entry List or in the search results. RoboJournal is able to store separate entries for the Entries and Search tabs simultaneously but each tab can only display one entry at a time in the Output Pane.
19. Tag List — This is where RoboJournal displays the tags assigned to the current entry. This list reads, "This entry has not been tagged yet" if there is no tag data available for the entry. If the entry was tagged previously and the tag data later removed, this list reads, "No tag data for this entry".
20. Tab Header — This is used to visually separate the Tag List from the Entry Body.
21. Entry Body — This term refers to the entirety of the text in each entry. The Entry Body is usually of a different length for each entry. RoboJournal forbids a zero-length Entry Body.
22. Entry Header — This term refers to the area that stores the date and timestamp of when the entry was made. It also displays the user's full name and the day of week the entry was made (if those features are enabled).
23. Entry Title — This is the title of the current entry. The size of this element is relative to the text size you have selected for the Entry Body text.

Making a Connection

You must initiate a new connection before you can work with a journal. A connection creates a persistent link between the RoboJournal interface and the database you are currently working with. As such, all actions initiated during the session only affect the journal you are currently connected to. RoboJournal only supports one connection at a time; you must run multiple instances of RoboJournal if you need to work with more than one journal simultaneously.

The following procedure establishes a new connection:

  1. Click the Connect toolbar button (indicated by the small red circle in Figure 3).
  2. The New Connection dialog is displayed:Figure 3Figure 3: New Connection Dialog (in MySQL mode).
    FYI: The Host, Database, and Username fields on the New Connection dialog are automatically populated with default values if the Always suggest default values option is enabled in the RoboJournal Preferences window. You can temporarily override this functionality by unchecking the Use default host/database and Use default user account checkboxes on the New Connection dialog.

    After doing so, the Host, Database, and Username fields are cleared and made writable so you can enter your own values. This override is only effective for the current session; the next connection automatically reverts back to the default values. You must edit the default settings if you wish to make your override values permanent.

    Every text field in the New Connection dialog is automatically blank and writable if RoboJournal is not configured to suggest default values.
  3. Enter the appropriate password into the Password field (indicated by the large oval in Figure 3). The contents of the Password field are always obscured for security reasons.
  4. Click the OK button to continue.

Figure 4Figure 4: RoboJournal main window in Connected Mode.

RoboJournal attempts to make the connection using the values you provided once you have clicked the OK button in the New Connection dialog. Successfully establishing a connection takes RoboJournal out of Default State and causes it to enter Connected Mode (as shown in Figure 4). All previously-locked program functionality becomes available while RoboJournal is in Connected Mode. However, the Connect button is locked during this time because it is currently impossible to have multiple connections in a single instance of RoboJournal.

In RoboJournal version 0.4.1 (or newer), RoboJournal displays the Tag Reminder window immediately after login if your journal contains any untagged entries. You are required to tag the entries in the list or close the Tag Reminder window before you can access the rest of your journal.

FYI: RoboJournal utilizes a "sanity check" mechanism for determining the compatibility of the database you are currently attempting to connect to. A database is considered to be "sane" if it matches a predefined table structure; this causes RoboJournal to recognize it as a valid journal. RoboJournal refuses to load any database that fails the sanity check.

Disconnecting

You can disconnect at any time while RoboJournal is in Connected Mode. Disconnecting returns RoboJournal to a condition very similar to Default State. Once you have disconnected, you can make another connection or quit the program.

FYI: You can safely quit without disconnecting but RoboJournal usually requires you to confirm your decision.

Click the Disconnect toolbar button (indicated by the red circle in Figure 5) to proceed:

Figure 5Figure 5: The Disconnect toolbar button immediately terminates the current connection.

Writing a New Entry

You can write a new entry at any time once RoboJournal is in Connected Mode. Each entry is represented by a node in the Chronological Entry List. Unlike day, month, or year-level nodes, entry-level nodes are marked with an icon and have no subordinate nodes.

Whenever you create a new entry, RoboJournal automatically keeps track of the date and time for the new record. This allows you to focus entirely on the new entry's content. RoboJournal automatically assigns a unique identification number (not shown in the user interface) to each entry to prevent conflicts between two or more entries with the same title and/or body text. This identification number is never used more than once in the same journal. There is a theoretical limit to how many entries a MySQL-based journal may contain but the number is so large (within the billions) that nobody ever comes close to reaching it. Therefore, feel free to write as often as you want.

The following procedure adds a new entry to the current journal:

  1. Click the Write in Journal toolbar button on the RoboJournal main window.Figure 6Figure 6: Click the Write in Journal button (indicated in red).
  2. The Editor dialog is displayed:Figure 6Figure 7: RoboJournal Editor dialog in Write (new entry) Mode.
  3. Enter a title for this entry in the Entry Title field.
  4. Write the body text for this entry in the large text area.
    FYI: The Character count and Remaining characters values indicate how much longer the body text may be (MySQL allows up to 65,535 characters). If the Remaining characters value is negative, RoboJournal prevents you from saving the entry until this value is greater than or equal to zero.
  5. When finished, click the Save this Entry button (indicated by the circled toolbar icon in the following screenshot):Figure 8Figure 8: The Save this Entry toolbar button (button labels have been disabled in RoboJournal Preferences).
  6. RoboJournal displays a confirmation message ("entry_title" was successfully added to your journal) if the save was successful.
  7. The new entry is added to the Chronological Entry List. If desired, you may click on the new entry to display its contents in the Entry Output Pane:Figure 9Figure 9: The new entry is displayed in the Chronological Entry List.

Modifying an Existing Entry

The Editor dialog allows you to modify existing entries after they have been saved to the journal database. You may change the title and body text in any way you see fit. However, RoboJournal prevents you from changing the date because that often creates problems with the rest of the database. Any special characters/conditions in the entry text that are affected by post-processing (e.g. ellipsis characters, dashes, smart quotes, etc.) revert to their original state during the editing session in order to make them easier to work with. All applicable post-processing features are automatically re-applied after the changes have been saved.

The following procedure allows you to change an existing entry:

  1. Select the entry that is to be modified by clicking on its node in the Chronological Entry List (as shown in the large red oval in Figure 10). Figure 10Figure 10: Selecting the entry to be modified.
  2. Click the Modify Entry toolbar button (indicated by the small red circle in Figure 10). You can visually distinguish the Modify Entry button from the Write in Journal button by the Modify Entry button's orange pencil color, its central position in the button group, and its horizontal red lines.
  3. The Editor window is displayed with the entry data pre-loaded into the appropriate fields:Figure 11Figure 11: Existing entry text loaded into Editor (in Edit Mode).
  4. Make all necessary changes.
  5. Click the Save Changes toolbar button (indicated by the red circle in Figure 12) to commit your changes to the database. The Save Changes button replaces the Save this Entry toolbar button while the Editor dialog is in Edit Mode. If you wish to cancel your edits, you can click the Discard Changes button (located to the immediate right of the Save Changes button) to return to the main window.Figure 12Figure 12: Saving changes once the edits are complete.
  6. A confirmation message ("entry_title" was successfully updated.) is displayed if RoboJournal was able to save the entry successfully. Otherwise, RoboJournal displays a message explaining what went wrong. In either case, click the OK button in the dialog to continue.
  7. If the save was successful, the updated entry is displayed in the Entry Output Pane on the RoboJournal main window. Figure 13Figure 13: The updated entry is shown immediately after the edit process is completed.

Deleting an Entry

RoboJournal's delete function provides a way to easily remove the currently selected entry from the database. You should always exercise caution when using this feature because delete operations are permanent. The only way to undo an accidental deletion is to restore an earlier version of the journal that contains the lost data from a backup.

  1. Select the entry to be deleted by clicking on its node in the Chronological Entry List (shown in the large oval area in Figure 14).
  2. Click the Delete Entry toolbar button (indicated by the small circle in Figure 14). Figure 14Figure 14: Select the entry you wish to delete and click the Delete Entry button.
  3. A confirmation dialog is displayed as a safety measure. This dialog is your last opportunity to cancel the delete operation. Click the OK button to approve the delete operation or click the Cancel button to abort. Figure 15Figure 15: A confirmation dialog is displayed if safety protocols are enabled. This is your last chance to abort.
    FYI: RoboJournal skips Step 3 if the Always Show Confirmation Dialogs option is disabled in RoboJournal Preferences. In such cases, the delete operation is instantaneous and provides no chance to abort even if you click the Delete Entry toolbar button accidentally! You should treat the Delete Entry function with extreme caution if confirmation dialogs have been disabled.
  4. You are returned to the main window regardless of your decision in the previous step. If you chose to continue with the delete operation, the previously-selected entry is now gone: Figure 16Figure 16: The entry you deleted is no longer displayed in the Chronological Entry List.

All entries in the current journal are displayed in ascending chronological order; the newest entry is always the first on the list while the oldest entry (in the current range) is on the very bottom. RoboJournal has convenient ways to browse adjacent entries in the current journal if you wish to read it in a chronological fashion. This is accomplished by clicking the Previous Entry and Next Entry toolbar buttons on the RoboJournal main window:Figure 17Figure 17: The Previous Entry and Next Entry buttons allow easy sequential browsing.

Clicking the Next Entry or the Previous Entry toolbar button increments or decrements the current entry by one record. The focused (selected) entry in the Chronological Entry List automatically jumps to the appropriate adjacent record whenever the entry is changed this way. If there is no record available before or after the current entry because you are viewing the oldest or newest entry, the affected button locks to indicate that further browsing in that direction is impossible (as shown in Figure 18 where the Next Entry button is locked because the latest entry is already being displayed).

You can use the Latest Entry toolbar button (indicated by the red circle in Figure 18) to immediately jump to the most recent entry in the database:Figure 18Figure 18: You can use the Latest Entry button to display the newest entry at any time. RoboJournal can also be configured to display the latest entry by default.

Tagging an Entry

Refer to the "Working With Tags" documentation.

Exporting an Entry

Refer to the "Exporting Journal Entries" documentation.

Searching for an Entry

Refer to the "Using the Search Function" documentation.

=======
RoboJournal Documentation

for version 0.5

RoboJournal Fundamentals

Sections

FYI: Toolbar button labels have been disabled in every screenshot of the main window used in this documentation to ensure that all buttons are fully visible for demonstration purposes.
  1. Default State
  2. Main Window Anatomy
  3. Making a Connection
    1. Initiating a MySQL Connection
    2. Connected Mode
  4. Disconnecting
  5. Writing a New Entry
  6. Modifying an Existing Entry
  7. Deleting an Entry
  8. Navigating the Timeline
  9. Tagging an Entry
  10. Exporting an Entry
  11. Searching for an Entry

Default State

RoboJournal is ready for regular day-to-day use once it has been properly configured through first-run mode. When RoboJournal is started under normal conditions, the main window is displayed:

RoboJournal Main Window in Default StateFigure 1: RoboJournal's main window in "Default State".

The initial configuration of the main window (immediately after starting the program) is known as the "Default State" in this documentation. Most of the main window's functionality (except Connect and RoboJournal Preferences) is locked while the program is in the Default State because the locked functions specifically affect the current journal; in other words, there is nothing for these functions to do without an active connection. Therefore, you must make a connection to unlock this functionality.

Under normal conditions, the main window is visible for the duration of the entire session. A "session" is defined as being the span of time the current instance of RoboJournal has been running; each session begins when you start RoboJournal and ends when you exit. Many configuration settings (especially arguments) remain unchangable for the duration of a session while others can be redefined during the current session (and therefore affect program behavior without requiring RoboJournal to restart).

Main Window Anatomy

On a superficial level, RoboJournal's main window consists of two large areas bifurcated by a movable splitter object. The Timeline (Item 12 in Figure 2), previously known as the Chronological Entry List, is always located on the left side of the splitter while the Entry Output Pane (Item 18) is always on the right. The rest of the window contains a movable toolbar, a status bar, and the standard drop-down File, Edit, etc. menus common to most Windows programs.

RoboJournal's toolbar can be docked on the left, right, or top margin of the main window. The toolbar cannot be free-floated or discarded (although it can be temporarily hidden by selecting the appropriate option in the Show sub-menu on the Window drop-down menu). You can change the location of the toolbar by dragging the toolbar docking widget to the position where you want the toolbar to be or by selecting the desired position from the Toolbar position sub-menu on the Window drop-down menu. For ease of identification, the toolbar docking widget is always on the far left side of the toolbar or on the very top if the toolbar is currently docked vertically (the docking widget's appearance may vary by operating system). Your mouse pointer changes to a four-directional arrow while it is hovering over the toolbar docking widget. The layout automatically adjusts once the toolbar has been moved to a new location. Be advised that moving the toolbar this way is temporary; the only way to permanently change the toolbar orientation is by selecting a different default position in RoboJournal Preferences.

The splitter object separates the Timeline from the Entry Output Pane and determines how much window space is allocated to each. By default, the splitter divides the RoboJournal main window roughly in half on the vertical axis, regardless of window size. If desired, you can drag the splitter bar left or right to shrink or grow the sizes of the Timeline and the Entry Output Pane. Moving the splitter all the way left or all the way right collapses the object on that side, rendering it invisible. The remaining object expands to fill the entire horizontal axis of the window. If you move the splitter bar to a new location, RoboJournal saves the coordinates and automatically applies them to future sessions. RoboJournal reverts the splitter to the default position if the coordinate data becomes unavailable for some reason or if you choose to move the splitter back to the default position (via the Revert splitter position command on the Window drop-down tool menu).

The following diagram and table provide a complete explanation of each element in the main window layout. Each numbered item in Figure 2 corresponds to the table row bearing the same number:

Figure 2Figure 2: RoboJournal main window elements identified by number (the toolbar has been docked to the left for more convenient numbering).


1. Connect toolbar button — Establishes a connection to a journal database.
2. Disconnect toolbar button — Terminates the current connection.
3. Latest toolbar button — Causes RoboJournal to jump to the most recent entry in the Timeline.
4. Previous Entry toolbar button — Displays the entry immediately before the currently-selected item in the Timeline (if possible).
5. Next Entry toolbar button — Displays the entry immediately after the currently-selected item in the Timeline (if possible).
6. Manage Tags toolbar button — Launches the Manage Tags dialog (affecting the currently-selected entry in the Timeline).
7. Export Content toolbar button — Displays the Entry Exporter dialog (affecting the currently-selected entry in the Timeline).
8. Write in Journal toolbar button — Launches the Editor dialog in "Write" (new entry) mode.
9. Modify Entry toolbar button — Launches the Editor dialog in "Edit" mode (affecting the currently-selected entry in the Timeline).
10. Delete Entry toolbar button— Deletes the currently-selected entry in the Timeline.
11. RoboJournal Preferences toolbar button — Displays the RoboJournal Preferences dialog.
12. Timeline — Displays entries (in the current range) from the current journal in chronological order from newest to oldest using a hierarchical tree format. Entries are usually grouped by the year and month in which they were created.

FYI: This item was known as the Chronological Entry List in previous versions of RoboJournal.
13. Entries tab — Clicking this tab causes RoboJournal to display the Timeline on the left side of the main window splitter.
14. Connection Indicator — This text provides information about the current connection (i.e. the database type, the database name, and the host on which the database is located).
15. Search tab — Displays the search interface in the place of the Timeline on the left side of the main window splitter.
16. Username Indicator — This field displays the username of the active user. The avatar icon located to the left of the name switches depending on the user's gender.
17. Entry Count/Entry Range Indicator — The Entry Count displays the number of entries in the current journal OR the number of entries in the allotted range (if a year range has been set in RoboJournal Preferences). The Entry Count displays the total number of entries in the journal if there is no entry range set.

The Entry Range Indicator is displayed if an entry limit has been set and you have decided to display the entry range indicator. For instance, Entry Count WITH Range Indicator means RoboJournal is displaying six entries made over the course of two years.

18. Entry Output Pane — This large area is used to display the currently-selected entry in the Timeline or in the search results. RoboJournal is able to store separate entries for the Entries and Search tabs simultaneously but each tab may only display one entry at a time in the Output Pane.
19. Tag List — This is where RoboJournal displays the tags assigned to the current entry. This list reads, "This entry has not been tagged yet" if there is no tag data available for the entry. If the entry was tagged previously and the tag data later removed, this list reads, "No tag data for this entry".
20. Tab Header — This is used to visually separate the Tag List from the Entry Body.
21. Entry Body — This term refers to the entirety of the text in each entry. The Entry Body is usually of a different length for each entry. RoboJournal forbids a zero-length Entry Body.
22. Entry Header — This term refers to the area that stores the date and timestamp of when the entry was made. It also displays the user's full name and the day of week the entry was made (if those features are enabled).
23. Entry Title — This is the title of the current entry. The size of this element is relative to the text size you have selected for the Entry Body text.

Making a Connection

You must initiate a new connection before you can work with a journal. A connection creates a persistent link between the RoboJournal interface and the database you are currently working with. As such, all actions initiated during the session only affect the journal you are currently connected to. RoboJournal only supports one connection at a time; you must run multiple instances of RoboJournal if you need to work with more than one journal simultaneously. The New Connection dialog has been dramatically improved for RoboJournal 0.5 and later. These changes take advantage of the new Favorite Journals system to make it far easier to keep track of and work with multiple databases.

To initiate a new connection, click the Connect toolbar button (indicated by the red circle in Figure 3). RoboJournal displays the New Connection dialog:
Figure 3Figure 3: New Connection Dialog (in MySQL mode).

The New Connection dialog in RoboJournal 0.5 and later consists of a tabbed interface that segregates its functionality by database type. The current tab determines which type of connection will be used for the next session. Only one tab is accessible at any given time to eliminate the possibility of conflicting login parameters. This behavior is governed by the current database type set through RoboJournal Preferences. For instance, the MySQL tab is always unlocked and displayed by default on the New Connection dialog while RoboJournal is in MySQL mode.

Initiating a MySQL Connection

When displayed, the New Connection dialog automatically retrieves a list of your favorite MySQL journals on a given host (the current item in the Host drop-down list) and uses this data to populate the Journal drop-down list. Subsequently changing the current item in the Host list automatically refreshes the Journal list contents with the current list of favorite journals on the new host.

For the sake of simplicity, all screenshots in this section depict the New Connection dialog separately from the main window. In reality, the New Connection dialog is always superimposed over the main window. The following procedure establishes a new MySQL connection:

  1. Select the appropriate Host from the drop-down list (indicated by the red oval in Figure 4). The default host is always selected automatically. In most RoboJournal deployments, this list only contains a single entry for "localhost" (the current computer). Figure 4Figure 4: Selecting the appropriate Host from the drop-down list.
  2. Your default MySQL journal is always selected by default in the Journal drop-down list. Select the desired item from the list if you need to use a different journal.Figure 5Figure 5: The Journal list displays your current "favorite" journals for the current Host.
    FYI: The Journal list only includes your current favorite journals in order to keep the list at a managable length. Each journal you must access on a regular basis should be marked as a favorite on the MySQL Journal page in RoboJournal Preferences.
  3. Under normal conditions, the Username field automatically contains the default user account. Proceed to the next step if you wish to use the default user account. Otherwise, you must first uncheck the Use default user account checkbox before you can enter a different user account value in the Username field.
  4. Enter the password that goes with the username you specified into the Password field. The contents of the Password field are always obscured for security reasons. Figure 6Figure 6: RoboJournal is ready to connect once all fields have been completed.
  5. Click the Connect button (indicated in Figure 6) to initiate a connection with the specified journal. If the connection attempt is successful,  RoboJournal displays the contents of the journal in the main window:Figure 4Figure 7: RoboJournal main window in Connected Mode.

Connected Mode

Successfully establishing a database connection takes RoboJournal out of Default State and causes it to enter Connected Mode (as shown in Figure 7). All previously-locked program functionality becomes available while RoboJournal is in Connected Mode. The Connect button locks once a connection has been established because RoboJournal does not support parallel connections in a single instance of the program.

In RoboJournal version 0.4.1 and later, RoboJournal displays the Tag Reminder window immediately after login if your journal contains any untagged entries. You are required to tag the entries in the list or close the Tag Reminder window before you can access the rest of your journal.

In RoboJournal 0.5 and later, RoboJournal displays a notification/warning message after each login if the date override feature is enabled for the current session.

FYI: During each connection attempt, RoboJournal utilizes a "sanity check" test to determine whether the current database is compatible. A database is considered to be "sane" if it matches a predefined table structure. As a precaution, RoboJournal refuses to load any database that fails the sanity check.

Disconnecting

You can disconnect at any time while RoboJournal is in Connected Mode. Disconnecting returns RoboJournal to a condition very similar to Default State. Once you have disconnected, you can make another connection or quit the program. For the sake of convenience, you can safely quit RoboJournal without disconnecting first.

Click the Disconnect toolbar button (indicated by the red circle in Figure 5) to proceed:

Figure 5Figure 5: The Disconnect toolbar button immediately terminates the current connection.

Writing a New Entry

You can write a new entry at any time once RoboJournal is in Connected Mode. Each entry is represented by a node in the Timeline. Unlike day, month, or year-level nodes, entry-level nodes are marked with an icon and have no subordinate nodes.

Whenever you create a new entry, RoboJournal automatically keeps track of the date and time for the new record. This allows you to focus entirely on the new entry's content. RoboJournal automatically assigns a unique identification number (not shown in the user interface) to each entry to prevent conflicts between two or more entries with the same title and/or body text. This identification number is never used more than once in the same journal. There is a theoretical limit to how many entries a MySQL-based journal can contain but the number is so large (within the billions) nobody ever comes close to reaching it. Therefore, feel free to write as often as you want.

The following procedure adds a new entry to the current journal:

  1. Click the Write in Journal toolbar button on the RoboJournal main window.Figure 6Figure 6: Click the Write in Journal button (indicated in red).
  2. The Editor dialog is displayed:Figure 6Figure 7: RoboJournal Editor dialog in Write (new entry) Mode.
  3. Enter a title for this entry in the Entry Title field. As you type, the Editor window title bar changes from "Untitled Entry" to match whatever text the Entry Title field currently contains.
  4. Write the body text for this entry in the large text area. Paragraphs should be separated by whitespace (one empty line). Indenting the first line of each paragraph is optional.
    FYI: The Character count and Remaining characters values indicate how much longer the body text can be (MySQL allows up to 65,535 characters). RoboJournal allows you to save the entry if the Remaining characters value is positive (negative values are displayed in red and indicate how many characters must be removed before the entry can be saved).
  5. When finished, click the Save this Entry button (indicated by the circled toolbar icon in Figure 8):Figure 8Figure 8: The Save this Entry toolbar button.
  6. RoboJournal displays a confirmation message ("entry_title" was successfully added to your journal) if the save was successful.
  7. The new entry is added to the Timeline. If desired, you can click on the new entry to display its contents in the Entry Output Pane:Figure 9Figure 9: The new entry is displayed in the Timeline.

Modifying an Existing Entry

The Editor dialog allows you to modify existing entries after they have been saved to the journal database. You can change the title and body text in any way you see fit. However, RoboJournal prevents you from changing the date because that would create integrity problems in the database. Any special characters/conditions in the entry text affected by post-processing (e.g. ellipsis characters, dashes, smart quotes, etc.) revert to their original state during the editing session to make them easier to work with. All applicable post-processing features are automatically re-applied after the changes have been saved.

The following procedure allows you to change an existing entry:

  1. Select the entry that is to be modified by clicking its node in the Timeline (as shown in the large red oval in Figure 10). Figure 10Figure 10: Selecting the entry to be modified.
  2. Click the Modify Entry toolbar button (indicated by the small red circle in Figure 10). You can visually distinguish the Modify Entry button from the Write in Journal button by the Modify Entry button's orange pencil color, its central position in the button group, and its horizontal red lines.
  3. The Editor window is displayed with the entry data pre-loaded into the appropriate fields:Figure 11Figure 11: Existing entry text loaded into Editor (in Edit Mode).
  4. Make all necessary changes.
  5. Click the Save Changes toolbar button (indicated by the red circle in Figure 12) to commit your changes to the database. The Save Changes button replaces the Save this Entry toolbar button while the Editor dialog is in Edit Mode. If you wish to cancel your edits, you can click the Discard Changes button (located to the immediate right of the Save Changes button) to return to the main window.Figure 12Figure 12: Saving changes once the edits are complete.
  6. A confirmation message ("[Entry title]" was successfully updated.) is displayed if RoboJournal saved the entry successfully. Otherwise, RoboJournal displays a message explaining what went wrong. In either case, click the OK button in the dialog to continue.
  7. If the save was successful, the updated entry is displayed in the Entry Output Pane on the RoboJournal main window. Figure 13Figure 13: The updated entry is shown immediately after the edit process is completed.

Deleting an Entry

RoboJournal's delete function provides a way to easily remove the current entry from the database. You should always exercise caution when using this feature because all deletions are permanent. The only way to undo an accidental deletion is by restoring a backup of the journal that contains the lost data (recovery is impossible if no such backup exists). You should back up your journal on a regular basis for this reason alone.

  1. Select the entry to be deleted by clicking its node in the Timeline (shown in the large oval area in Figure 14).
  2. Click the Delete Entry toolbar button (indicated by the small circle in Figure 14). Figure 14Figure 14: Select the entry you wish to delete and click the Delete Entry button.
  3. A confirmation dialog is displayed as a safety measure. This dialog is your last opportunity to cancel the delete operation. Click the OK button to approve the delete operation or click the Cancel button to abort. Figure 15Figure 15: A confirmation dialog is displayed if safety protocols are enabled. This is your last chance to abort.
    FYI: RoboJournal skips Step 3 if the Always Show Confirmation Dialogs option is disabled in RoboJournal Preferences. In such cases, the delete operation is instantaneous and provides no chance to abort even if you click the Delete Entry toolbar button accidentally! You should treat the Delete Entry function with extreme caution if confirmation dialogs have been disabled.
  4. You are returned to the main window regardless of your decision in the previous step. If you chose to continue with the delete operation, the previously-selected entry is gone: Figure 16Figure 16: The entry you deleted is no longer displayed in the Timeline.

All entries in the current journal are displayed in ascending chronological order; the newest entry is always the first on the list while the oldest entry (in the current range) is on the very bottom. RoboJournal has convenient ways to browse adjacent entries in the current journal if you wish to read it in a chronological fashion. This is accomplished by clicking the Previous Entry and Next Entry toolbar buttons on the RoboJournal main window:Figure 17Figure 17: The Previous Entry and Next Entry buttons allow easy sequential browsing.

Clicking the Next Entry or the Previous Entry toolbar button increments or decrements the current entry by one record. The focused (selected) entry in the Timeline automatically jumps to the appropriate adjacent record whenever the entry is changed this way. If there is no record available before or after the current entry because you are viewing the oldest or newest entry, the affected button locks to indicate that further browsing in that direction is impossible (as shown in Figure 18 where the Next Entry button is locked because the latest entry is already being displayed).

You can use the Latest Entry toolbar button (indicated by the red circle in Figure 18) to immediately jump to the most recent entry in the database:Figure 18Figure 18: Clicking the Latest Entry button always displays the first (most recent) item in the Timeline. RoboJournal can also be configured to display the latest entry by default.

Tagging an Entry

Refer to the "Working With Tags" documentation.

Exporting an Entry

Refer to the "Exporting Journal Entries" documentation.

Searching for an Entry

Refer to the "Using the Search Function" documentation.

>>>>>>> experimental