Merge lp:~ralph-lange/epics-appdev/new-promptgroups into lp:~epics-documenters/epics-appdev/3.16

[Ralph Lange]

Document the changes in https://code.launchpad.net/~epics-core/epics-base/new-promptgroups

Unmerged revisions

=== modified file 'tex/databaseDefinition.tex'
--- tex/databaseDefinition.tex	2016-01-08 17:17:05 +0000
+++ tex/databaseDefinition.tex	2016-04-26 11:53:58 +0000
@@ -58,7 +58,7 @@
     field(field_name, field_type) {
         asl(asl_level)
         initial("init_value")
-        promptgroup(gui_group)
+        promptgroup("gui_group")
         prompt("prompt_value")
         special(special_value)
         pp(pp_value)
@@ -356,7 +356,7 @@
     field(field_name, field_type) {
         asl(as_level)
         initial("init_value")
-        promptgroup(gui_group)
+        promptgroup("gui_group")
         prompt("prompt_value")
         special(special_value)
         pp(pp_value)
@@ -389,7 +389,9 @@
 \item [initial] Provides an initial (default) value for the field.
 
 \index{promptgroup -- field descriptor rules}
-\item [promptgroup] The group to which the field belongs, for database configuration tools.
+\item [promptgroup] The gui group to which the field belongs, for database configuration tools (DCTs).
+To support DCTs in sorting the gui groups, the names used in Base start with a two-digit number,
+followed by a space-dash-space sequence.
 
 \index{prompt -- field descriptor rules}
 \item [prompt] A prompt string for database configuration tools.
@@ -469,42 +471,45 @@
 \item [prompt\_value] A prompt value for database configuration tools.
 
 \index{gui\_group -- field definition}
-\item [gui\_group] This must be one of the following:
-
-\begin{itemize}
-\item \verb|GUI_COMMON|
-\item \verb|GUI_ALARMS|
-\item \verb|GUI_BITS1|
-\item \verb|GUI_BITS2|
-\item \verb|GUI_CALC|
-\item \verb|GUI_CLOCK|
-\item \verb|GUI_COMPRESS|
-\item \verb|GUI_CONVERT|
-\item \verb|GUI_DISPLAY|
-\item \verb|GUI_HIST|
-\item \verb|GUI_INPUTS|
-\item \verb|GUI_LINKS|
-\item \verb|GUI_MBB|
-\item \verb|GUI_MOTOR|
-\item \verb|GUI_OUTPUT|
-\item \verb|GUI_PID|
-\item \verb|GUI_PULSE|
-\item \verb|GUI_SELECT|
-\item \verb|GUI_SEQ1|
-\item \verb|GUI_SEQ2|
-\item \verb|GUI_SEQ3|
-\item \verb|GUI_SUB|
-\item \verb|GUI_TIMER|
-\item \verb|GUI_WAVE|
-\item \verb|GUI_SCAN|
-
-This information is for use by Database Configuration Tools.
-This is defined only for fields that can be given values by database configuration tools.
-File \verb|guigroup.h| contains all possible definitions.
-This allows database configuration tools to group fields together by functionality, not just order them by name.
-This feature has seldom been used, so many record types do not have appropriate values assigned to some fields.
-
-\end{itemize}
+\item [gui\_group] The gui group to which the field belongs, for database configuration tools (DCTs).
+Gui groups allow DCTs to group fields of a record by functionality, for convenient user access.
+
+The gui group is defined only for fields that can be set by DCTs.
+
+There is no limited fixed set of allowed groups.
+Instead, gui group tags are collected when parsing the DBD information, and used to populate a global list.
+To support sorting and handling of groups, the names used in Base use the following conventions:
+
+\begin{itemize}
+\item Names start with a two-digit number followed by a space-dash-space sequence.
+This allows consistent sorting of groups.
+\item In many-of-the-same-kind cases (e.g. 21 similar inputs) fields are distributed over multiple groups.
+Once-only fields appear in the group that starts with a "major" number (\verb|<n>|0 or \verb|<n>|5).
+The groups with the multiple instances follow in +1 increments.
+This allows more sophisticated treatment, e.g. showing the first group open and the other groups collapsed.
+\end{itemize}
+
+Record types may define their specific gui groups.
+However, to improve consistency, records should use the following groups from Base if possible.
+(This set also shows an alternative group sharing an existing sorting number.)
+
+\begin{itemize}
+\item [10 - Common] General fields that are common to all or many record types
+\item [20 - Scan] Scanning mechanism, priority and related properties
+\item [30 - Action] Record type specific behavior and processing action
+\item [40 - Link] Links and related properties
+\item [40 - Input] Input links and properties
+\item [50 - Output] Output links and properties
+\item [60 - Convert] Conversion between raw and engineering values
+\item [70 - Alarm] Alarm related properties, severities and thresholds
+\item [80 - Display] Client related configuration, strings, deadbands
+\item [90 - Simulate] Simulation mode related properties
+\end{itemize}
+
+NOTE: Older versions of Base contained a header file \verb|guigroup.h| defining a fixed set of gui groups strings
+and their matching index numbers.
+This file has been removed. Instead, the static database access library provides functions to convert between
+numerical codes and string tags. See \ref{subsec:Get Field Prompt} for details.
 
 \index{special\_value -- field definition}
 \item [special\_value] Must be one of the following:

=== modified file 'tex/staticDatabaseAccess.tex'
--- tex/staticDatabaseAccess.tex	2015-01-28 23:44:33 +0000
+++ tex/staticDatabaseAccess.tex	2016-04-26 11:53:58 +0000
@@ -6,7 +6,7 @@
 EPICS provides two sets of database access routines:
 Static Database Access and Runtime Database Access.
 Static database access can be used on Unix or IOC database files.
-Runtime database requires an initialized IOC databases.
+Runtime database requires an initialized IOC database.
 Static database access is described in this chapter, runtime database access in the next chapter.
 
 Static database access provides a simplified interface to a database, i.e. much of the complexity is hidden.
@@ -408,16 +408,27 @@
 does not point to a field or if the default value is NULL.
 
 \subsection{Get Field Prompt}
+\label{subsec:Get Field Prompt}
 
 \begin{verbatim}
 char *dbGetPrompt(DBENTRY *pdbentry);
-int   dbGetPromptGroup(DBENTRY *pdbentry); 
+int   dbGetPromptGroup(DBENTRY *pdbentry);
+char *dbGetPromptGroupNameFromKey(DBBASE *pdbbase, const short key);
+short dbGetPromptGroupKeyFromName(DBBASE *pdbbase, const char *name);
 \end{verbatim}
 
 \index{dbGetPrompt}
 \index{dbGetPromptGroup}
+\index{dbGetPromptGroupNameFromKey}
+\index{dbGetPromptGroupKeyFromName}
 The \verb|dbGetPrompt| routine returns the character string prompt value, which provides a short description of the field.
-\verb|dbGetPromptGroup| returns the field group as described in guigroup.h.
+\verb|dbGetPromptGroup| returns the field's gui group key.
+
+Conversion between the gui group key and the gui group name is provided by two conversion functions.
+\verb|dbGetPromptGroupNameFromKey| returns a pointer to a static string containing the name of the gui group,
+\verb|NULL| for an invalid key.
+\verb|dbGetPromptGroupKeyFromName| returns the numerical key related to the specified gui group string,
+\verb|0| if the string is not a valid gui group.
 
 \section{Manipulating Record Attributes}