gcylcrc.tex

\section{Gcylc GUI (cylc gui) Config File Reference}
\label{GcylcRCReference}

\lstset{language=bash}

This section defines all legal items and values for the gcylc user config file,
which should be located in \lstinline=$HOME/.cylc/gcylc.rc=. Current settings
can be printed with the \lstinline=cylc get-gui-config= command.

\subsection{Top Level Items}

\subsubsection{dot icon size}

Set the size of the task state dot icons displayed in the text and dot
views.

\begin{myitemize}
\item {\em type:} string
\item {\em legal values:} ``small'' (10px), ``medium'' (14px), ``large'' (20px),
        ``extra large (30px)''
\item {\em default:} ``medium''
\end{myitemize}

\subsubsection{initial side-by-side views}

Set the suite view panels initial orientation when the GUI starts.
This can be changed later using the ``View'' menu ``Toggle views side-by-side''
 option.

\begin{myitemize}
\item {\em type:} boolean (False or True)
\item {\em default:} ``False''
\end{myitemize}

\subsubsection{initial views}

Set the suite view panel(s) displayed initially, when the GUI starts.
This can be changed later using the tool bar.

\begin{myitemize}
\item {\em type:} string (a list of one or two view names)
\item {\em legal values:} ``text'', ``dot'',  ``graph''
\item {\em default:} ``text''
\item {\em example:} \lstinline@initial views = graph, dot@
\end{myitemize}

\subsubsection{maximum update interval}

Set the maximum (longest) time interval between calls to the suite for data
update.

The update frequency of the GUI is variable. It is determined by considering
the time of last update and the mean duration of the last 10 main loops of the
suite.

In general, the GUI will use an update frequency that matches the mean duration
of the suite's main loop. In quiet time (or if the suite is not contactable),
it will gradually increase the update interval (i.e. reduce the update
frequency) to a maximum determined by this setting.

Increasing this setting will reduce the network traffic and hits on the suite
process.  However, if a quiet suite starts to pick up activity, the GUI may
initially appear out of sync with what is happening in the suite for the
duration of this interval.

\begin{myitemize}
\item {\em type:} ISO 8601 duration/interval representation (e.g.\ 
\lstinline=PT10S=, 10 seconds, or \lstinline=PT1M=, 1 minute).
\item {\em default: PT15S}
\end{myitemize}

\subsubsection{sort by definition order}

If this is not turned off the default sort order for task names and
families in the dot and text views will the order they appear in the
suite definition. Clicking on the task name column in the treeview will
toggle to alphanumeric sort, and a View menu item does the same for the
dot view.  If turned off, the default sort order is alphanumeric and
definition order is not available at all.

\begin{myitemize}
\item {\em type:} boolean
\item {\em default:} True
\end{myitemize}


\subsubsection{sort column}

If ``text'' is in \lstinline@initial views@ then \lstinline@sort column@ sets
the column that will be sorted initially when the GUI launches. Sorting can be
changed later by clicking on the column headers.

\begin{myitemize}
    \item {\em type:} string
    \item {\em legal values:} ``task'', ``state'', ``host'', ``job system'',
        ``job ID'', ``T-submit'', ``T-start'', ``T-finish'', ``dT-mean'',
        ``latest message'', ``none''
    \item {\em default:} ``none''
    \item {\em example:} \lstinline@sort column = T-start@
\end{myitemize}


\subsubsection{sort column ascending}

For use in combination with \lstinline@sort column@, sets whether the column will
be sorted using ascending or descending order.

\begin{myitemize}
    \item {\em type:} boolean
    \item {\em default:} ``True''
    \item {\em example:} \lstinline@sort column ascending = False@
\end{myitemize}


\subsubsection{task filter highlight color}

The color used to highlight active task filters in gcylc. It must be a name
from the X11 rgb.txt file, e.g.\ \lstinline=SteelBlue=; or a
{\em quoted} hexadecimal color code, e.g.\ \lstinline="#ff0000"= for red (quotes
are required to prevent the hex code being interpreted as a comment).

\begin{myitemize}
    \item {\em type:} string
    \item {\em default:} \lstinline=PowderBlue=
\end{myitemize}


\subsubsection{task states to filter out}

Set the initial filtering options when the GUI starts. Later this can be
changed by using the "View" menu "Task Filtering" option.

\begin{myitemize}
\item {\em type:} string list
\item {\em legal values:} waiting, held, queued, ready, expired, submitted,
submit-failed, submit-retrying, running, succeeded, failed, retrying, runahead
\item {\em default:} runahead
\end{myitemize}


\subsubsection{transpose dot}

Transposes the content in dot view so that it displays from left to right rather
than from top to bottom. Can be changed later using the options submenu
available via the view menu.

\begin{myitemize}
    \item {\em type:} boolean
    \item {\em default:} ``False''
    \item {\em example:} \lstinline@transpose dot = True@
\end{myitemize}


\subsubsection{transpose graph}

Transposes the content in graph view so that it displays from left to right
rather than from top to bottom. Can be changed later using the options submenu
via the view menu.

\begin{myitemize}
    \item {\em type:} boolean
    \item {\em default:} ``False''
    \item {\em example:} \lstinline@transpose graph = True@
\end{myitemize}


\subsubsection{ungrouped views}

List suite views, if any, that should be displayed initially in an
ungrouped state. Namespace family grouping can be changed later
using the tool bar.

\begin{myitemize}
\item {\em type:} string (a list of zero or more view names)
\item {\em legal values:} ``text'', ``dot'',  ``graph''
\item {\em default:} (none)
\item {\em example:} \lstinline@ungrouped views = text, dot@
\end{myitemize}


\subsubsection{use theme}

Set the task state color theme, common to all views, to use initially. The
color theme can be changed later using the tool bar.  See
\lstinline@etc/gcylc.rc.eg@ and \lstinline@etc/gcylc-themes.rc@ in the Cylc
installation directory for how to modify existing themes or define your own.
Use \lstinline@cylc get-gui-config@ to list available themes.

\begin{myitemize}
\item {\em type:} string (theme name)
\item {\em legal values:} ``default'', ``solid'', ``high-contrast'',
    ``color-blind'', and any custom or user-modified themes.
\item {\em default:} ``default''
\end{myitemize}


\subsubsection{window size}

Sets the size (in pixels) of the cylc GUI at startup.

\begin{myitemize}
    \item {\em type:} integer list: x, y
    \item {\em legal values:} positive integers
    \item {\em default:} 800, 500
    \item {\em example:} \lstinline@window size = 1000, 700@
\end{myitemize}


\subsection{[themes]}

This section may contain task state color theme definitions.

\subsubsection[{[}THEME{]}]{[themes] \textrightarrow [[THEME]]}

The name of the task state color-theme to be defined in this section.

\begin{myitemize}
\item {\em type:} string
\end{myitemize}

\paragraph[inherit]{[themes] \textrightarrow [[THEME]] \textrightarrow inherit}

You can inherit from another theme in order to avoid defining all states.

\begin{myitemize}
\item {\em type:} string (parent theme name)
\item {\em default:} ``default''
\end{myitemize}

\paragraph[defaults]{[themes] \textrightarrow [[THEME]] \textrightarrow defaults}

Set default icon attributes for all state icons in this theme.

\begin{myitemize}
\item {\em type:} string list (icon attributes)
\item {\em legal values:} \lstinline@"color=COLOR"@, \lstinline@"style=STYLE"@, \lstinline@"fontcolor=FONTCOLOR"@
\item {\em default:} (none)
\end{myitemize}

For the attribute values, COLOR and FONTCOLOR can be color names from the X11
rgb.txt file, e.g.\ \lstinline=SteelBlue=; or hexadecimal color codes, e.g.\ 
\lstinline@#ff0000@ for red; and STYLE can be ``filled'' or ``unfilled''.
See \lstinline@etc/gcylc.rc.eg@ and \lstinline@etc/gcylc-themes.rc@ in
the Cylc installation directory for examples.

\paragraph[STATE]{[themes] \textrightarrow [[THEME]] \textrightarrow STATE}

Set icon attributes for all task states in THEME, or for a subset of them if
you have used theme inheritance and/or defaults. Legal values of STATE are
any of the cylc task proxy states: {\em waiting, runahead, held, queued, ready,
submitted, submit-failed, running, succeeded, failed, retrying, submit-retrying}.

\begin{myitemize}
\item {\em type:} string list (icon attributes)
\item {\em legal values:} \lstinline@"color=COLOR"@, \lstinline@"style=STYLE"@, \lstinline@"fontcolor=FONTCOLOR"@
\item {\em default:} (none)
\end{myitemize}

For the attribute values, COLOR and FONTCOLOR can be color names from the X11
rgb.txt file, e.g.\ \lstinline=SteelBlue=; or hexadecimal color codes, e.g.\ 
\lstinline@#ff0000@ for red; and STYLE can be ``filled'' or ``unfilled''.
See \lstinline@etc/gcylc.rc.eg@ and \lstinline@etc/gcylc-themes.rc@ in
the Cylc installation directory for examples.