Categories

Categories control where and when events are displayed.

A new category is created by selecting the categories list pane and hitting ^N on the keyboard or "new element" in entry menu.

Categories have a short name that is used by events as a tag to attach to the category and to construct URLs to link to events attached to the category.

A category can be a child of another category. This allows a category to be part of its parent category and to be shown nested inside the parent. This usually means that there is some kind of relation between the events shown in the child category and those shown in the parent.

Although categories are used to define the position and size for displayed events, the user does not need to assign values for either. The QViewer will lay out a category and all its children automatically if position or size are not defined. There are other useful properties of categories, but only a name is required.

There is no absolute limit to the number of categories that can be nested inside a parent, or to the number of generations of parents and children a category can contain, but several hundred categories and generations are practical.

category name

The category name is a short tag that is used:

  • In the list of categories when attaching an event to categories.
  • When an event is attached to more than one category, the category names appear in the list of links from the event.
  • In the parent list of categories that are descendants of the category.
  • In the information displayed by a browser when information is requested about an event.

category parent

The parent field indicates where this category belongs in a hierarchy of nested categories. Parents are similar to file pathnames on many operating systems. They are a list of category names separated by a slash ( / ) character. The last category in the list is the one that directly contains the category being defined.

The category names in a parent are not used for attaching events. These categories don't have to be defined in a timeline unless events will be attached to it in that timeline.

There are two forms that a parent list takes. Absolute pathnames start with slash ( / ). A special category called the top category stands for the entire category plane. Absolute pathnames start with the immediate child of the top category. If an absolute pathname starts with the slash alone, the defined category is laid out as an immediate child of the top category.

Relative pathnames start with a category name or are entirely empty. The QViewer will try to attach the path to the path of other categories that contain the first category in the pathname. If no other category paths mention the first category in the path, the first category becomes an immediate child of the top category.

If the pathname is empty, the pathname is really a relative path consisting of the category's name alone.

example 1

A single category whose name is Supreme Court, and parent is /

The Supreme Court category is a direct child of the top category.

example 2

A single category whose name is John Jay, and parent is Supreme Court

Without any other instance of Supreme Court, it becomes a direct child of the top category. The category John Jay is a child of the category Supreme Court

example 3

Two categories:

One named John Jay, with the parent Supreme Court

Another named Decisions, with the parent / US History / Supreme Court

The John Jay category has a relative parent. Because Supreme Court is defined in the Decisions category parent, the two references to Supreme Court are merged together. Both John Jay and Decisions are nested inside a single category.

Categories can be defined in multiple timeline files. If their parents are the same or if the parents can be merged, the categories represent the same location on the display.

category layout

fixed position (x,y,w,h)

proportion (height / width)

free

The category layout property determines the method and parameters that the QViewer will use to determine the size and position of the category relative to its parent category. It is related to the child layout of its immediate parent category.

Free means the QViewer will decide the size and position of category.

Proportion means the QViewer, like free, will decide the size and position of the category. However, the relative height and width can be set here. If the proportion parameter equals one, the category is square (the default for free). If proportion is greater than one, the height is greater than the width. If the proportion is less than one, the width is greater than the height.

A fixed position sets the size and position of the category relative to its parent category. Each category has its own coordinate systems where the lower left corner is (0.0, 0.0) and the upper right corner is (1.0, 1.0). The fixed position is expected to fit inside the parent category's boundaries.

category child layout

automatic layout

fixed position layout

mixed layout

The category child layout chooses the method that the QViewer uses to determine the size and position of a category's child categories.

Automatic layout means that the QViewer sets the size and location of the child categories. All the children should be free or proportional.

Fixed position expects all the children are fixed by having positions and sizes assigned in their category layout.

Mixed defines an area in the category that can be used to lay out categories with free and proportion category layouts. Fixed position children are handled as in the fixed position case.

category note

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 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.

© 2011 Quotidian Incorporated