An event is an entry in a timeline file that indicates something has occurred at some time or for some duration in time.
A new event is created by selecting the events list pane and hitting ^N on the keyboard or new element in entry menu.
At a minimum events must have values for these properties:
- a starting time
- a category
Events almost always have a name. This is text that appears in the event label on the display.
The start time is the beginning time for the event. The end time is the ending time of the event, but is optional. If an end time is given, the event is a state between the start and end times. If the end time is not given, an end time is inferred from the start time's precision. For example, if the start time is given as 1821 then the event starts at the first moment of 1 Jan 1821 and the inferred end time is the first moment of 1 Jan 1822.
The event is always attached to at least one category. The start and end times provide the location and size for one dimension (time) in the three-dimensional display. The category provides the location and size in the other two dimensions.
When an event is attached to a category, the author can set minimum (min) and maximum (max) values. These are related to the level of detail setting in the QViewer and usually represent a measure of the relative importance of that event in that category. Events are displayed when the QViewer level is between their min and max values. The default settings are 0 for min and 100 for max.
The QViewer user, by increasing the level of detail, is often asking for more events to be shown. But an author of a timeline is free to assign any level to any event. The author could cause a different set of events to become visible and thereby completely change the content of a category at each level.
Because events can be attached to multiple categories, the event may have a different min and max value for each category. This is particularly useful when a category is nested inside another. The same event in the outer category may appear at a higher level than in a more detailed inner category. This allows the outer category to present a summary of the most important events in its nested categories.
An event may be drawn with different colors and labels when drawn in different categories. This can be accomplished by giving the parent categories different classes and defining styles for the events in those classes.
Events have other properties to add information to the event and to control how an event appears or behaves when visible or selected on the QViewer display.
- event name
- popup text
The name is text that appears in a label next to the event when displayed in the QViewer. The name is usually a short title or very brief description of the event. The text can extend to multiple lines if needed. The maximum length of label lines is set at 65 characters in this version of Quotidian.
The precision of the starting time expression can be used as the duration of an event if no end time is given.
Now can be used as a start time in non-relative timelines.
Event end is the ending time for this event.
An end time is not required. If one is given, the event is the state between the instant represented by the event start and the instant represented by this time value. If no end value is given, the precision of the event's starting time is used as the duration of the event.
In non-relative timelines, the end time can be a datetime, or it can be a relative value representing the event's duration. This duration always starts with "+" and is later added to the start time value to get a non-relative end value.
In relative timelines, the end time must be a relative time. The relative end time is not the duration of the event. Rather, it is, like the start time, a time relative to the timeline's origin.
The edit panel for the categories field contains a list of the defined categories. The event can be placed in a category by selecting the checkbox next to the category name. An event can be added to any number of categories.
The min and max fields are for setting the range of levels where this event is drawn. Generally, higher level of detail values imply that the event is of less importance than other events with lower numbers in the same category. The default min (0) and max (100) values cause the event to always be drawn.
The color and label fields in the category list allow events to be drawn differently in the categories to which the event is attached. The values of this fields override the values defined for the event.
A source is a tag that refers to an entry in the Sources list. Since it is possible that many or all events in a timeline will share the same source, it makes sense to define the source in one place and have each event reference it.
Each event also has a one-line location field that allows the source to be specialized. Typically, this is used to specify a page number in the main source citation, but this is not required. Both the source citation field and the location field can be used as the author wishes.
The source is not used by the QViewer, but may be shown in the user's browser if event info is requested.
parameter = "dodecahedron"
parameter = "octahedron"
An extension is attached to an event by adding the name of the extensions class and the URL of the folder or jar file that contains the compiled class.
For example, the Shape extension
parameter is left blank
The parameter field is used to provide any options needed by the extension. The creator of the extension should provide some documentation about what the extention does and what parameters are available. In the Shape extension, an empty parameter (or "Sphere") means that the event will be drawn as a sphere. The first image shows the example with no parameter. The second has parameter set to "dodecahedron". The third has parameter set to "octahedron".
the extension edit panel
data format dialog with info from extension
Some extensions require more input data than can be comfortably put in the single line of the parameter field. The extension should be able to tell the editor what kind of data is needed. The "Data Format" button will load the extension and request this information.
The extension argument list provides a place to enter data used by the extension in the format it requests.
The editor will try to load the code for the extension and query it to find whether it expects an extension argument list and what types of data should be in the list.
If the extension code cannot be loaded, if it is not available or has not yet been written, the author can fill in the names and types of the extension data. This information is not saved with the timeline, but allows data input by supplying a temporary format for the extension argument list. This feature will probably be used rarely.
The extension's class, pathname, and parameter can be made sticky, but not the argument list.
A sound file or source can be attached to an event by entering a URL in the sound edit panel. The author can use the browse button to choose a file on the local machine or drag and drop a sound file into the edit panel.
When the sound edit panel is active, play and stop commands are added to the menu and toolbar. This allows the author to preview the sound file.
There are three sound modes:
Sounds play when the display time is between the start and end times of an event that has an attached sound. When this mode is selected, the sound is played once. Moving the current sound out of the event and back causes it to play again.
The sound plays and repeats as long as the display time is between the start and end of the event.
The sound is mapped onto the event, starting at the event's start time. The sound is played only when QViewer's realtime mode is on. In this case, the event will have usually have the same duration as the sound. If the author moves the display time to 55 seconds after the start of the event, then turns on realtime mode, the sound will start playing at a point 55 seconds into the sound.
As the category attached to this event is moved away from the center of the screen, the Sound Rolloff category hiding value can be used to reduce the volume.
An image can be attached to an event by entering a URL in the image edit panel. The author can use the browse button to open a file dialog to choose a file on the local machine, or drag and drop an image file into the edit panel.
A number of fields in the edit panel determine when and how an image is displayed.
- display location (x, y, scale)
An image is normally drawn starting at the lower left corner of the category when in the future view. The image can be positioned in the category by setting the X and Y positions. This can vary from (0.0, 0.0), the default, lower left in the future view, to (1.0, 1.0) upper right in the future view.
The scale is a percentage of the category size using the larger dimension of the image.
- image pixel size
The image pixel size is important, not for the drawing process itself (the QViewer will find the image size when it loads the file), but because having the size in the image description allows the QViewer to calculate, in advance of file loading, which images are most prominent in the display.
Image files can be quite large and may be downloaded from a slow network connnection. The QViewer ranks unloaded images based on how much of the display it takes up and how of the image is visible (not behind other display objects or images).
It is not the actual size of the image height and width that are important for this pre-loading step, but their ratio. If the image file is not available, an estimate by the author can still be useful.
- show image button
The "show image" button allows the author to preview the image. Loading the image in the editor also automatically sets the pixel height and width.
- image visibility
These settings determine the display directions where the image is visible.
Both events and categories have a place for relevent text information or notes. This text is shown when an event is selected and the QViewer is being directed to show event information in the browser. The form and content of this text is not specified by Quotidian and is not used directly by the QViewer. However, because this text is often shown embedded in a webpage, some limited HTML formatting can be useful.
The link field of events uses the same mechanism as that in the locator/links lists. However, one end of the link is known - the source locator is always this event. Defining links in an event provides a shortcut for the more general linking in the locator/links lists. Only the title (normally part of a link) and the URL (normally part of the destination locator) must be provided.
When the user double-clicks on an event or hits the current links button on the toolbar, the QViewer looks in the list of links associated with the event and activates the one with the "select" attribute.
If this is a link to a timeline, the QViewer will display the timeline and event in the URL. Otherwise, the URL is sent to the user's web browser. This is a powerful complement to using links in web pages to direct the QViewer to display events.
Various browsers respond in different ways to requests to show a link. Some will show the requested page in the same browser tab. Others will open a new window or tab for each request.