How to use California's Quick Add
Introduction
California, a GNOME 3 calendar application, differs from most other calendar applications by allowing you to create events by typing in as much or little relevant information as you like. California will parse your text details into a full-fledged event and add it to your calendar. This allows for quickly describing the event as though typing a message to a friend or coworker ("meeting on Friday at 10am") without having to navigate a panel of choices and checkboxes (although California makes that available as well).
Although this parser is designed to interpret natural language, it is limited and not flawless. It works best if you understand some basic patterns for entering information and remember guidelines about how to phrase your event details.
What follows are examples in English. Translations will differ, obviously. We hope to have these instructions translated in the future with the appropriate keywords.
tl;dr
For the impatient, here are some sample quick-add sentences that generate meaningful results:
Manga & Anime Festival this Thursday
Bingo Nite at Moe's from 6pm to 8pm
Darts game in 2 hours at Moe's for 45 minutes
Mayor Quimby's payoff due every Monday and Wednesday at 11am
Lisa's birthday every April 4
More detailed information follows that explains the more interesting features of the parser and how word your details for best results.
Keywords and patterns
The quick add parser is fairly simple as far as natural-language parsers go. What's important to understand is that it uses keywords and patterns to determine what's being described.
Some important patterns:
The time of day should be formatted (for example) "7pm", "7 pm", "7:00pm", or "19:00". 12- and 24-hour time are respected no matter your locale or System Settings. You cannot use "1900", as the parser can't distinguish between it and a plain number (such as a street number).
- Dates can be described as day/month or day/month/year with some leeway about ordering. For example, "March 1st" and "1 Mar" describe the same date.
- Days of week can be written in full ("Sunday") or with your locale's common abbreviation ("Sun").
- California assumes the start date/time is specified first and the end date/time later. Other details can be placed in between them. For example:
Movie at 19:00 at Paramount Theater until 23:30
- If the end date is before the start date, California will reverse them, but this is not guaranteed to work as expected every time.
Some important keywords:
- Keywords that signal a date or time follow include "at", "from", "to", "on", "until" and "this". A time-based keyword allows for California to be more lax about parsing:
Meet at 7
refers to 7am or 7pm, depending on which time will next arrive (is the soonest in the future).
- The keyword indicating a duration (length of time) is being described is "for":
Meet for 2 hours
- The keyword for a delay in the start time is "in":
Meet in 15 minutes
- A recurring event is indicated by "every":
Meet every Sunday
- The event location is assumed to follow the word "at". Since "at" may indicate time or place, California uses context and pattern-matching (see above time/date patterns) to determine what you mean.
The important thing to understand is that every unparsed word after "at" is included in the location:
Meet at 2pm to 4pm at Gold Dust Saloon for drinks and laughs
will set the event location to "Gold Dust Saloon for drinks and laughs".
* By default, the location is added to the event summary. If you prefer more concise summaries, use the at-sign ("@") to indicate location:
7pm Dinner at Tadich Grill
will give you a summary of "Dinner at Tadich Grill", while
7pm Dinner @ Tadich Grill
will give you a summary of "Dinner".
* The at-sign can also be used for time:
Dinner @ 7pm
Ways to quickly add events
California currently offers three ways to start using Quick Add to enter event details. Some of the ways of starting a Quick Add gives California a little extra information it can use to better parse your details and prevent extra typing from you.
No matter how you start Quick Add, if California can't deduce enough information to generate a valid event (a summary and a starting and ending date and/or time is required), California will open the event editor for you to finish entering details.
Add an event to any day, any time
The "+" button in the top toolbar will open a Quick Add window for you to enter your event details. (You can also use its hot key: Ctrl+N.) There is no context for this type of event. If you don't specify a date, the current day is used.
Add an event to a specific day
In Month view, double-clicking a day will open a Quick Add window. In Week view, double-click one of the areas at the top of the day columns where all-day events are displayed.
The day you selected is considered the starting day of the event. If you specify a date ("May 3rd"), that is considered the ending day of the event. If you specify event times ("10am", "1700"), those will be treated as starting and ending times. Without times, the event is considered an all-day or a multi-day event.
Add an event to a specific time
In Week view, double-clicking in the hourly column will open a Quick Add window for that day and time for a one-hour event. Alternately, you can click-and-drag in the hourly column to specify the start and end times of the event.
The day and times are considered the start and end of the event. Any dates or times you specify in your event details are ignored.
Event details
Once a Quick Add window is open (through one of the ways described above), you can start typing event details for California to parse. What follows are some simple patterns to give you an idea of how to use this feature.
All-day events
Let's say you have an all-day conference this Thursday. If you double-click on that day in California's Month view, you can simply enter:
Manga & Anime Festival
Or, you can press the "+" button (or Ctrl+N) and type this:
Manga & Anime Festival this Thursday
You probably want to make a note where the festival is occurring:
Manga & Anime Festival this Thursday at Airport Hyatt, Shelbyville
Not only is the event added for the upcoming Thursday, the Location field is set to "Airport Hyatt, Shelbyville"
Perhaps it's for this weekend (Saturday and Sunday):
Manga & Anime Festival Saturday and Sunday at Airport Hyatt, Shelbyville
or
Manga & Anime Festival this weekend at Airport Hyatt, Shelbyville
Timed events
In Week view, you can click-and-drag to set the event's start and end time. You can type it just as easily, however:
Bingo Nite at Moe's at 6pm
This creates an event at location "Moe's" starting at 6pm and ending at 7pm. If an end time is not specified, one hour is assumed. If no date is specified (and one was not clicked on in the interface), the current day is assumed.
If Bingo Nite goes for two hours, you can enter an end time or a duration:
Bingo Nite at Moe's from 6pm to 8pm
or
Bingo Nite at Moe's at 6pm for 2 hours
If you don't know the exact time something starts but know it's happening a fixed amount of time in the future, you can specify a start delay, and even a duration rather than an end time:
Darts game in 2 hours at Moe's for 45 minutes
Recurring events
The Quick Add parser can also create recurring events, that is, events that happen repeatedly at regular times.
If the event happens every day:
Treehouse meeting every day at 3pm
If something happens weekly—that is, on one or more days of the week, but not every day—name the days of the week:
Mayor Quimby's payoff due every Monday and Wednesday at 11am
or
Krusty's Funtime every weekday at 3pm
If the event happens monthly or on a specific day of the month:
Meet with Reverend Lovejoy every 1st Sunday
Yearly events like birthdays and anniversaries:
Lisa's birthday every April 4
More information
The Quick Add parser is still in development and some text may not generate expected results. If this is the case and the text you type can reasonably be parsed, please let the California team know:
File a ticket for California: This is good if there's an obvious problem with how the parser interprets your text.