Org API

Cancel the running clock by removing the start timestamp.

Cancel the clock located by clock.

Clock in to the clock located by clock. If necessary, clock-out of the currently active clock.

Clock out of the clock located by clock.

Reset org-clock-current-task to nil.

Show subtree times in the entire buffer. If total-only is non-nil, only show the total time for the entire file in the echo area.

Use M-x org-clock-remove-overlays to remove the subtree times.

Find the location where the next clock line should be inserted. When find-unclosed is non-nil, first check if there is an unclosed clock line and position cursor in that line.

Form a clock-string, that will be shown in the mode line. If an effort estimate was defined for the current item, use 01:30/01:50 format (clocked/estimated). If not, show simply the clocked time like 01:50.

Get the clocked time for the current item in minutes. The time returned includes the time spent on this task in previous clocking intervals.

Return the time from which clock times should be counted. This is for the currently running clock as it is displayed in the mode line. This function looks at the properties LAST_REPEAT and in particular CLOCK_MODELINE_TOTAL and the corresponding variable org-clock-modeline-total and then decides which time to use.

Get the clocktable data for file file, with parameters params. file is only for identification - this function assumes that the correct buffer is current, and that the wanted restriction is in place. The return value will be a list with the file name and the total file time (in minutes) as 1st and 2nd elements. The third element of this list will be a list of headline entries. Each entry has the following structure:

(LEVEL HEADLINE TIMESTAMP TIME)

LEVEL: The level of the headline, as an integer. This will be

the reduced leve, so 1,2,3,... even if only odd levels
are being used.

HEADLINE: The text of the headline. Depending on params, this may

already be formatted like a link.

TIMESTAMP: If params require it, this will be a time stamp found in the

entry, any of SCHEDULED, DEADLINE, NORMAL, or first inactive,
in this sequence.

TIME: The sum of all time spend in this tree, in minutes. This time

will of cause be restricted to the time block and tags match
specified in PARAMS.

Go to the currently clocked-in entry, or to the most recently clocked one. With prefix arg select, offer recently clocked tasks for selection.

Push a marker to the clock history.

Start the clock on the current item. If necessary, clock-out of the currently active clock. With a prefix argument select (C-u), offer a list of recently clocked tasks to clock into. When select is C-u C-u, clock into the current task and mark is as the default task, a special task that will always be offered in the clocking selection, associated with the letter d.

=i=nsert a line for the clock selection menu. And return a cons cell with the selection character integer and the marker pointing to it.

Return the value of org-clock-into-drawer, but let properties overrule. If the current entry has or inherits a CLOCK_INTO_DRAWER property, it will be used instead of the default value; otherwise if the current entry has or inherits a LOG_INTO_DRAWER property, it will be used instead of the default value. The default is the value of the customizable variable org-clock-into-drawer, which see.

Return non-nil if clock is currently running. The return value is actually the clock marker.

Load clock-related data from disk, maybe resuming a stored clock.

Mark current task as default task.

Add to or set the effort estimate of the item currently being clocked. value can be a number of minutes, or a string with format hh:mm or mm. When the string starts with a + or a - sign, the current value of the effort property will be changed by that amount. This will update the "Effort" property of currently clocked item, and the mode line.

Show notification if we spent more time than we estimated before. Notification is shown only once.

Stop the currently running clock. If there is no running clock, throw an error, unless fail-quietly is set.

Clock out if the current entry contains the running clock. This is used to stop the clock after a TODO entry is marked DONE, and is only done if the variable org-clock-out-when-done is not nil.

Set up hooks for clock persistence.

Play sound as configured by org-clock-sound. Use alsa's aplay tool if available.

Put an overlays on the current line, displaying time. If level is given, prefix time with a corresponding number of stars. This creates a new overlay and stores it in org-clock-overlays, so that it will be easy to remove.

Remove empty clock drawer in the current subtree.

Remove the occur highlights from the buffer. beg and end are ignored. If noremove is nil, remove this function from the before-change-functions in the current buffer.

Create a table containing a report about clocked time. If the cursor is inside an existing clocktable block, then the table will be updated. If not, a new clocktable will be inserted. The scope of the new clock will be subtree when called from within a subtree, and file elsewhere.

When called with a prefix argument, move to the first clock table in the buffer and update it.

Resolve an open org-mode clock. An open clock was found, with dangling possibly being non-nil. If this function was invoked with a prefix argument, non-dangling open clocks are ignored. The given clock requires some sort of user intervention to resolve it, either because a clock was left dangling or due to an idle timeout. The clock resolution can either be:

(a) deleted, the user doesn't care about the clock
(b) restarted from the current time (if no other clock is open)
(c) closed, giving the clock X minutes
(d) closed and then restarted
(e) resumed, as if the user had never left

The format of clock is (CONS MARKER START-TIME), where MARKER identifies the buffer and position the clock is open at (and thus, the heading it's under), and START-TIME is when the clock was started.

Resolve =clock= given the time =resolve-to=, and the present. =clock= is a cons cell of the form (MARKER START-TIME).

Persist various clock-related data to disk. The details of what will be saved are regulated by the variable org-clock-persist.

Save relative positions of markers in region.

Select a task that recently was associated with clocking.

Set org-clock-current-task to the task currently clocked in.

Return two times bordering a special time range. Key is a symbol specifying the range and can be one of today, yesterday, thisweek, lastweek, thismonth, lastmonth, thisyear, lastyear. A week starts Monday 0:00 and ends Sunday 24:00. The range is determined relative to time. time defaults to the current time. The return value is a cons cell with two internal times like the ones returned by current time or encode-time. if as-strings is non-nil, the returned times will be formatted strings.

Sum the times for each subtree. Puts the resulting times in minutes as a text property on each headline. tstart and tend can mark a time range to be considered. headline-filter is a zero-arg function that, if specified, is called for each headline in the time range with point at the headline. Headlines for which headline-filter returns nil are excluded from the clock summation.

Return time, clocked on current item in total.

Compute a time fraction in percent. total s a time string like 10:21 specifying the total times. strings is a list of strings that should be checked for a time. The first string that does have a time will be used. This function is made for clock tables.

Change CLOCK timestamps synchronously at cursor. updown tells whether to change 'up or 'down.

Increase CLOCK timestamps at cursor.

Increase CLOCK timestamps at cursor.

If this is a CLOCK line, update it and return t. Otherwise, return nil.

Return the clocking buffer if we are currently clocking a task or nil.

Return t when clocking a task.

Try to shift the :block date of the clocktable at point. Point must be in the #+BEGI=n=: line of a clocktable, or this function will throw an error. dir is a direction, a symbol left, right, up, or down. Both left and down shift the block toward the past, up and right push it toward the future. n is the number of shift steps to take. The size of the step depends on the currently selected interval size.

Step through the range to make a number of clock tables.

Check if this line starts a clock table, if yes, shift the time block.

Write out a clock table at position ipos in the current buffer. tables is a list of tables with clocking data as produced by org-clock-get-table-data. params is the parameter property list obtained from the dynamic block definition.