From 4137259fa6071d2790173f7935f06465df324264 Mon Sep 17 00:00:00 2001
From: deva <deva>
Date: Thu, 12 Feb 2009 15:29:50 +0000
Subject: Lots of changes in the widget documentation...

---
 design/widgets/altcombobox.tex  | 38 ++++++++++++++++++++++++++++++
 design/widgets/button.tex       |  4 ++++
 design/widgets/checkbox.tex     | 17 ++++++++++----
 design/widgets/combobox.tex     |  9 +++++++
 design/widgets/dbwidget.tex     | 45 +++++++++++++++++++++++++++++++++++
 design/widgets/frame.tex        | 16 ++++++++-----
 design/widgets/label.tex        |  8 ++++++-
 design/widgets/lineedit.tex     |  9 +++++--
 design/widgets/listbox.tex      | 10 ++++++++
 design/widgets/metawidget.tex   | 14 ++++++-----
 design/widgets/multilist.tex    | 52 +++++++++++++----------------------------
 design/widgets/radiobuttons.tex | 14 ++++++++---
 design/widgets/spacer.tex       |  7 ++++++
 design/widgets/textedit.tex     |  4 ++++
 design/widgets/window.tex       | 20 +++++++++-------
 15 files changed, 200 insertions(+), 67 deletions(-)
 create mode 100644 design/widgets/altcombobox.tex
 create mode 100644 design/widgets/dbwidget.tex

(limited to 'design/widgets')

diff --git a/design/widgets/altcombobox.tex b/design/widgets/altcombobox.tex
new file mode 100644
index 0000000..dc33b29
--- /dev/null
+++ b/design/widgets/altcombobox.tex
@@ -0,0 +1,38 @@
+% -*- coding: utf-8 -*-
+\subsubsection{\texttt{altcombobox} elementet}
+\label{altcombobox}
+En altcombobox fungerer fuldstændigt som en combobox (se kapitel \ref{combobox}),
+men den ene undtagelse at den udover item tags indeholder altitem tags.\\
+Dens funktion er udover at stille elementer til rådighed for udvælgelse, at give
+mulighed for at udfylde en alternativ widget istedet, men under samme navn.\\
+En altcombobox har samme attributer som combobox.\\
+\\
+Altcomboboxen indeholder udover item tags også et (og kun et) \texttt{altitem} tag
+som igen indeholder den widget som skal bruges som altrenativ.\\
+Et altitem tag har flg. attributter:
+\begin{itemize}
+\item \textit{caption} - Den tekst som skal vises for denne valgmulighed. Hvis
+  udeladt vises den uden tekst.
+\item \textit{value} - En værdi som kun bruges internt af systemet, men stadig
+  skal være unikt genkendelig fra de andre navne hos item tagsne.
+\item \textit{layout} - ``vbox'' eller ``hbox'', beskriver hvordan de indre widgets
+  skal lægges ud.
+\item \textit{innerwidget} - Navnet på den af de indre widgets som skal benyttes
+  som værdien hvis altitem'et er valgt.
+\end{itemize}
+Ved commit returneres altcomboboxens navn med det valgte items value, eller værdien
+af den indre widget.\\
+Ved sætning af data til altcomboboxen vil dne først forsøg at vælge et af de
+almindelige items, og hvis dette fejler, sætte værdien på dens indre widget.
+
+\begin{lstlisting}[title={Et eksempel på et altcombobox tag med item tags og et altitem tag indeni.}]
+<altcombobox name="foobar" value="option1" layout="vbox">
+  <item caption="Option 1" value="option1"/>
+  <item caption="Option 2" value="option2"/>
+  <altitem caption="Option 3" value="option3" innerwidget="foo"
+           layout="vbox">
+    <label caption="Bar:"/>
+    <lineedit name="foo" value="test"/>
+  </altitem>
+</altcombobox>
+\end{lstlisting}
diff --git a/design/widgets/button.tex b/design/widgets/button.tex
index e2bb00e..b9c2ab1 100644
--- a/design/widgets/button.tex
+++ b/design/widgets/button.tex
@@ -12,3 +12,7 @@ En knap har flg. attributter:
   journalen og ``reset'' fjerner alle indtastede data. Hvis udeladt
   vil en inaktiv knap blive produceret.
 \end{itemize}
+
+\begin{lstlisting}[title={Et eksempel på et button tag.}]
+<button caption="Gem" action="commit"/>
+\end{lstlisting}
diff --git a/design/widgets/checkbox.tex b/design/widgets/checkbox.tex
index 0becb88..cf73264 100644
--- a/design/widgets/checkbox.tex
+++ b/design/widgets/checkbox.tex
@@ -1,12 +1,19 @@
 % -*- coding: utf-8 -*-
 \subsubsection{\texttt{checkbox} elementet}
-En checkbox bruges til at aktivere eller deaktivere en given værdi ved
-hjælp af flueben.\\
+En checkbox bruges til skifte mellem to tekstuelle værdier.\\
 En checkbox har flg. attributter:
 \begin{itemize}
 \item \textit{caption} - Den tekst som skal vises i knappen. Hvis
   udeladt vises checkboxen uden tekst.
-\item \textit{value} - Den værdi som checkboxen har intielt. Kan
-  ``true'' eller ``false''. Hvis udeladt vil checkboxen få værdien
-  ``false''.
+\item \textit{value} - Den værdi som checkboxen har intielt.
+\item \textit{trueval} - Den tekstuelle værdi som den logiske værdi true
+  (checked) vil blive tillagt.
+\item \textit{falseval} - Den tekstuelle værdi som den logiske værdi false
+  (unchecked) vil blive tillagt.
 \end{itemize}
+
+\begin{lstlisting}[title={Et eksempel på et checkbox tag.}]
+<checkbox name="foobar" value="Denne checkbox er sand"
+          trueval="Denne checkbox er sand"
+          falseval="Denne checkbox er falsk"/>
+\end{lstlisting}
diff --git a/design/widgets/combobox.tex b/design/widgets/combobox.tex
index 2793bbe..feef168 100644
--- a/design/widgets/combobox.tex
+++ b/design/widgets/combobox.tex
@@ -1,5 +1,6 @@
 % -*- coding: utf-8 -*-
 \subsubsection{\texttt{combobox} elementet}
+\label{combobox}
 En combobox gruppe bruges til at vælge et element ud af en gruppe.\\
 En combobox har flg. attributter:
 \begin{itemize}
@@ -34,3 +35,11 @@ Et combobox item har flg. attributter:
   af gruppen hvis den er valgt ved commit.
 \end{itemize}
 Ved commit returneres comboboxens navn med det valgte items value.
+
+\begin{lstlisting}[title={Et eksempel på et combobox tag med item tags indeni.}]
+<combobox name="foobar" value="option1" layout="vbox">
+  <item caption="Option 1" value="option1"/>
+  <item caption="Option 2" value="option2"/>
+  <item caption="Option 3" value="option3"/>
+</combobox>
+\end{lstlisting}
diff --git a/design/widgets/dbwidget.tex b/design/widgets/dbwidget.tex
new file mode 100644
index 0000000..10c1e5b
--- /dev/null
+++ b/design/widgets/dbwidget.tex
@@ -0,0 +1,45 @@
+% -*- coding: utf-8 -*-
+\subsubsection{\texttt{dbwidget} elementet}
+En dbwidget fungerer på overfladen som en combobox i search mode
+(med type attributten sat til search), den har dog inden item tags
+som beskriver hvilke valgmuligheder der er.\\
+Istedet benytter den sig af lacy-fetch kald til en posgresql database.\\
+En dbwidget har flg. attributter:
+\begin{itemize}
+\item \textit{driver} - Den database driver som skal benyttes. I øjeblikket
+  kun ``QPSQL'' som er postgresql driveren.
+\item \textit{server} - Addressen på den server som driver databasen.
+\item \textit{port} - Portnummeret hvorpå databasen kan kontaktes.
+\item \textit{user} - Brugeren som databasen skal kontaktes med.
+\item \textit{password} - Det tilhørende password.
+\item \textit{database} - Databasen som skal kontaktes.
+\item \textit{select} - Et udtryk som svarer til SELECT delen af en SQL statement.
+\item \textit{from} - Navnet på den tabel som der skal selectes fra.
+\item \textit{where} - Den del af resultatet fra select som skal sammenlignes med
+  indholdet fra tekstfeltet i dbwidgeten. Hvis f.eks tekstfeltet indeholder
+  teksten ``ab'' og from attributen indeholder ``foo'', vil den konstruerede WHERE
+  statement til serveren blive ``WHERE foo = 'abc' ''. For at gøre søgningen
+  case-insensitiv bliver strengen fra tekstfeltet og resultatet i WHERE statementen
+  konverteret til lowercase indne sammenligningen udføres. 
+\item \textit{format} - Formatstrengen som bruges til at formatere datafelterne
+  fra databaseopslagene inden de indsættes i dbwidgetens tekstfelt. Modsat ander
+  steder i systemet er de tilrådighedværende navne de samme som dem i select
+  attributen og ikke navnene på de widgets som findes makroen. Med den ene forskel
+  fungerer formatstrengen som dokumenteret i kapitel \ref{format}.
+\end{itemize}
+
+\begin{lstlisting}[title={Et eksempel på et dbwidget tag, som laver søgning i en pilledatabase}]
+<dbwidget name="pille" driver="QPSQL" server="medicindb.dk"
+          user="postgres" database="medicin"
+          select="drugname" from="pills" where="drugname"
+          format="${drugname}"/>
+\end{lstlisting}
+
+\begin{lstlisting}[title={Et mere kompliceret eksempel som viser sammensatte strenge}]
+<dbwidget name="pille" driver="QPSQL" server="medicindb.dk"
+          user="postgres" database="medicin"
+          select="drugname, dosage" from="pills"
+          where="drugname || ' (' || dosage || ')'"
+          format="${drugname} (${dosage})"/>
+\end{lstlisting}
+
diff --git a/design/widgets/frame.tex b/design/widgets/frame.tex
index 7fd4294..00cacfa 100644
--- a/design/widgets/frame.tex
+++ b/design/widgets/frame.tex
@@ -2,16 +2,20 @@
 \subsubsection{\texttt{frame} elementet}
 En frame benyttes til at indsætte nestede elementer i makroen, såsom
 gruperinger af checkboxe.\\
+En farme kan bruges både som udsynligt layout element, eller som en
+navngiven grafisk boks (afhæmngig af værdien af \textit{caption} attributten).\\
 En frame har flg. attributter:
 \begin{itemize}
 \item \textit{caption} - Den tekst som skal vises i framen. Hvis
   udeladt vises framen som en tom ramme.
-\item \textit{border} - Elementets kant type. Kan have værdierne
-  ``plain'' eller ``raised'' Hvis udeladt benyttes laves ingen kant.
-\item \textit{padding} - En integer som er størelsen på paddingen på
-  elementet. Hvis udeladt benyttes elementets default padding.
-\item \textit{margin} - En integer som er størelsen på elementets
-  margin. Hvis udeladt benyttes elementets default margin.
 \item \textit{layout} - Framens layout engine. Kan have værdierne
   ``hbox'' eller ``vbox''. Hvis udeladt benyttes et vbox layout.
 \end{itemize}
+
+\begin{lstlisting}[title={Et eksempel på et frame tag.}]
+<frame caption="Overskrift" layout="hbox">
+   .
+   .
+   .
+</frame>
+\end{lstlisting}
diff --git a/design/widgets/label.tex b/design/widgets/label.tex
index 436fee5..b7f186e 100644
--- a/design/widgets/label.tex
+++ b/design/widgets/label.tex
@@ -1,6 +1,8 @@
 % -*- coding: utf-8 -*-
 \subsubsection{\texttt{label} elementet}
-En label benyttes til at indsætte beskrivejnde tekst i makroen.\\
+En label benyttes til at indsætte tekst i makroen.\\
+En label med tom \textit{caption} attribut kan bruges for at indsætte
+et mellemrum mellem to widgets.\\
 En label har flg. attributter:
 \begin{itemize}
 \item \textit{caption} - Den tekst som skal vises i labelen. Hvis
@@ -8,3 +10,7 @@ En label har flg. attributter:
 \item \textit{alignment} - Justeringen af teksten. Kan have værdierne
   ``left'', ``right'' eller ``center''. Hvis udeladt benyttes ``left''.
 \end{itemize}
+
+\begin{lstlisting}[title={Et eksempel på et label tag.}]
+<label caption="Foo Bar"/>
+\end{lstlisting}
diff --git a/design/widgets/lineedit.tex b/design/widgets/lineedit.tex
index 09876e3..3aeb392 100644
--- a/design/widgets/lineedit.tex
+++ b/design/widgets/lineedit.tex
@@ -7,8 +7,9 @@ indeholder valid data eller ej.\\
 Feltet er et et linies felt.\\
 En lineedit har flg. attributter:
 \begin{itemize}
-\item \textit{value} - Den tekst som skal vises i lineediten. Hvis
-  udeladt vil lineediten være tom.
+\item \textit{value} - Den initielle tekst som skal vises i
+  lineediten. Hvis udeladt vil lineeditens initielle værdi være den
+  tomme streng.
 \item \textit{regexp} - Et regulært udtryk som benyttes til at
   validere feltet. Hvis udeladt accepterer feltet alle inputs. Læs
   mere om de regulære udtryk her:
@@ -16,3 +17,7 @@ En lineedit har flg. attributter:
 \item \textit{readonly} - Beskriver om feltet er skrivebeskyttet.
   Hvis værdien er udeladt vil lineeditten kunne ændres af brugeren.
 \end{itemize}
+
+\begin{lstlisting}[title={Et eksempel på et lineedit tag.}]
+<lineedit name="foo" value="bar"/>
+\end{lstlisting}
diff --git a/design/widgets/listbox.tex b/design/widgets/listbox.tex
index dd9fe19..992cbde 100644
--- a/design/widgets/listbox.tex
+++ b/design/widgets/listbox.tex
@@ -24,3 +24,13 @@ Et listbox item har flg. attributter:
   vises i overskriften.
 \end{itemize}
 Ved commit returneres listboxens navn med det valgte items value.
+
+\begin{lstlisting}[title={Et eksempel på et listbox tag med item tags indeni.}]
+<listbox name="foobar" value="option1" layout="vbox">
+  <item caption="Option 1" value="option1"/>
+  <item type="separator"/>
+  <item caption="Option 2" value="option2"/>
+  <item type="header" caption="En overskrift"/>
+  <item caption="Option 3" value="option3"/>
+</listbox>
+\end{lstlisting}
diff --git a/design/widgets/metawidget.tex b/design/widgets/metawidget.tex
index dc09433..17521f4 100644
--- a/design/widgets/metawidget.tex
+++ b/design/widgets/metawidget.tex
@@ -5,20 +5,22 @@ widgets.\\
 En metawidget sammensætter værdierne fra de indre widgets igennem en
 formatstreng, og producerer på den måde et fælles output.\\
 De indre widgets kommer ikke til at indgå som en del af den ydre
-makros værdi liste.\\
+makros værdi liste, og deres værdier bliver således aldrig lagret
+direkte på serveren.\\
 En metawidget kan ikke sætte sin værdi i de indre widgets (grundet
 måden hvorpå disse oprindeligt er indsamlet), så en sat værdi i en
 meta widget vil blot blive ignoreret.\\
 En metawidget har flg. attributter:
 \begin{itemize}
 \item \textit{name} - Navnet på meta widgeten.
-\item \textit{layout} - ``hbox'' eller ``vbox''.
-\item \textit{format} - Format streng som beskriver hvordan værdierne
-  i den indre skal sammensættes (Se dokumentation for format strengens
-  format i kapitel \ref{format}).
+\item \textit{layout} - ``hbox'' eller ``vbox'', specificerer hvordan
+  de indre widgets skal lægges ud.
+\item \textit{format} - Formatstreng som beskriver hvordan værdierne
+  i de indre widgets skal sammensættes Se dokumentation for
+  formatstrengens format i kapitel \ref{format}.
 \end{itemize}
 
-\begin{lstlisting}
+\begin{lstlisting}[title={Et eksempel på en metawidget.}]
 <metawidget name="cave_metawidget" layout="vbox"
             format="Prep: ${prep}, Reak: ${reak}.">
   <textedit name="prep"/>
diff --git a/design/widgets/multilist.tex b/design/widgets/multilist.tex
index 8ca82eb..b49080b 100644
--- a/design/widgets/multilist.tex
+++ b/design/widgets/multilist.tex
@@ -1,43 +1,23 @@
 % -*- coding: utf-8 -*-
 \subsubsection{\texttt{multilist} elementet}
-En multilist bruges til at producere en række tekststrenge som alle
-vil blive tilføjet til en liste.\\
+En multilist bruges til at producere en liste af tekststrenge.\\
 En multilist har flg. attributter:
-%\begin{itemize}
-%\item \textit{value} - Inidikerer hvilket element på listen som skal være
-%  valgt initielt. Hvis udeladt eller ikke-matchende vil ingenting være valgt,
-%  hvilket vil svare til at et regulært udtryk på et tekstfelt ikke er
-%  opfyldt.
-%\end{itemize}
-En multiliste indeholder to undergrupper: en gruppe som beskriver
-preindsatte strenge, og en gruppe som indeholder widgets.\\
-Gruppen med de preindsatte strenge er tagget \texttt{items}, som har
-flg. attributer:
-%\begin{itemize}
-%\item \textit{value} - Inidikerer hvilket element på listen som skal være
-%  valgt initielt. Hvis udeladt eller ikke-matchende vil ingenting være valgt,
-%  hvilket vil svare til at et regulært udtryk på et tekstfelt ikke er
-%  opfyldt.
-%\end{itemize}
-\texttt{items} tagget indeholder således \texttt{item} tags som hver
-især beskriver en enkelt streng som skal indsættes. \texttt{item}
-tagget har flg. attributer:
 \begin{itemize}
-\item \textit{value} - 
+\item \textit{name} - Navnet på mulitlisten.
+\item \textit{layout} - ``vbox'' eller ``hbox'', specificerer hvordan
+de indre widgets skal lægges ud.
+\item \textit{value} - Den initielle værdi af multilisten.
+\item \textit{innerwidget} - Navnet på den indre widget som skal
+bruges til at tilføje nye strenge til listen.
 \end{itemize}
+Tekststrengene som bliver tilføjet vil i den endelige værdi for
+multilisten blive repræsenteret som en tekststreng med linieskift
+separering mellem rækerne i listen. Denne konstruktion lægger en
+naturlig begrænsning på indholdet af de enkelte rækker, idet de ikke
+kan indeholde linieskift.
 
-Et eksempel på en multilist:
-\begin{verbatim}
-<multilist>
-  <items>
-    <item>En streng</item>
-    <item>En streng mere</item>
-  </items>
-  <input layout="hbox">
-    <lineedit value="Skriv en værdi her"/>
-  </input>
+\begin{lstlisting}[title={Et eksempel på en multilist.}]
+<multilist layout="vbox" name="foo" innerwidget="bar">
+  <textedit name="bar" value="test"/>
 </multilist>
-\end{verbatim}
-
-Multilisten indeholder en række underwidgets som tilsammen konstruerer
-inputtet til strengkonstruktionen.
+\end{lstlisting}
diff --git a/design/widgets/radiobuttons.tex b/design/widgets/radiobuttons.tex
index e6afc8e..d69f873 100644
--- a/design/widgets/radiobuttons.tex
+++ b/design/widgets/radiobuttons.tex
@@ -4,16 +4,16 @@ En radiobuttons gruppe bruges til at vælge et element ud af en gruppe
 via radiobuttons.\\
 Radiobuttons gruppen har flg. attributter:
 \begin{itemize}
-\item \textit{value} - Inidikerer hvilken radiobutton i gruppen som skal være
+\item \textit{value} - Indikerer hvilken radiobutton i gruppen som skal være
   valgt initielt. Hvis udeladt eller ikke-matchende vil ingen radiobutton være
   valgt, hvilket vil svare til at et regulært udtryk på et tekstfelt ikke er
   opfyldt.
 \item \textit{layout} - Vinduets layout engine. Kan have værdierne
   ``hbox'' eller ``vbox''. Hvis udeladt benyttes et vbox layout.
 \end{itemize}
-Radiobuttons indeholder \texttt{item} tags som beskriver hvilke valgmuligheder
+Radiobuttons indeholder \texttt{radiobutton} tags som beskriver hvilke valgmuligheder
 den givne gruppe har.\\
-Et radiobutton item har flg. attributter:
+Et radiobutton tab har flg. attributter:
 \begin{itemize}
 \item \textit{caption} - Den tekst som skal vises i radiobuttonen. Hvis
   udeladt vises radiobuttonen uden tekst.
@@ -21,3 +21,11 @@ Et radiobutton item har flg. attributter:
   af gruppen hvis denne radiobutton er valgt ved commit.
 \end{itemize}
 Ved commit returneres radiobutton gruppens navn med den valgte radiobuttons value.
+
+\begin{lstlisting}[title={Et eksempel på et radiobuttons tag med radiobutton tags indeni.}]
+<radiobuttons name="foobar" value="option1" layout="vbox">
+  <radiobutton caption="Option 1" value="option1"/>
+  <radiobutton caption="Option 2" value="option2"/>
+  <radiobutton caption="Option 3" value="option3"/>
+</radiobuttons>
+\end{lstlisting}
diff --git a/design/widgets/spacer.tex b/design/widgets/spacer.tex
index dc40a6e..50e4b73 100644
--- a/design/widgets/spacer.tex
+++ b/design/widgets/spacer.tex
@@ -1,4 +1,11 @@
 % -*- coding: utf-8 -*-
 \subsubsection{\texttt{spacer} elementet}
 Et spacer element bruges for at pakke andre elementer i et layout.\\
+Hvis en spacer er indsat vil de resterende elementer blive så små som
+de kan og blive placeret så fjernt fra spaceren som muligt.\\
+Spaceren har ingen grafisk repræsenation.\\
 En spacer har ingen attributter.
+
+\begin{lstlisting}[title={Et spacer tag.}]
+<spacer />
+\end{lstlisting}
diff --git a/design/widgets/textedit.tex b/design/widgets/textedit.tex
index 4d1368a..2dfe924 100644
--- a/design/widgets/textedit.tex
+++ b/design/widgets/textedit.tex
@@ -15,3 +15,7 @@ En textedit har flg. attributter:
   mere om de regulære udtryk her:
   \verb|http://doc.trolltech.com/4.3/qregexp.html#introduction|
 \end{itemize}
+
+\begin{lstlisting}[title={Et eksempel på et textedit tag.}]
+<textedit name="foo" value="bar"/>
+\end{lstlisting}
diff --git a/design/widgets/window.tex b/design/widgets/window.tex
index 0d67cb0..b0aee3e 100644
--- a/design/widgets/window.tex
+++ b/design/widgets/window.tex
@@ -1,15 +1,19 @@
 % -*- coding: utf-8 -*-
 \subsubsection{\texttt{window} elementet}
-Et vindue benyttes som moder element, til at indsætte andre elementer
-i. Det vil optræde som et vindue på skærmen med kanter, vinduestitel,
-ikon osv.\\
+Et vindue er en repræsentation af en makro i makro oversigten
+(delforløbet).\\
 Et vindue har flg. attributter:
 \begin{itemize}
-\item \textit{caption} - Den tekst som skal vises i labelen. Hvis
-  udeladt vises ingen tekst i elementet.
-\item \textit{fixed} - Angiver om vinduet kan skaleres eller om det er
-  statisk. Kan have værdierne ``true'' eller ``false''. Hvis udeladt
-  vil vinduet kunne skaleres.
+\item \textit{caption} - Den grafiske overskift på makroen. Hvis
+undladt benyttes den tomme streng.
 \item \textit{layout} - Vinduets layout engine. Kan have værdierne
   ``hbox'' eller ``vbox''. Hvis udeladt benyttes et vbox layout.
 \end{itemize}
+
+\begin{lstlisting}[title={Et eksempel på et window tag.}]
+<window caption="Titel" layout="vbox">
+   .   
+   .
+   .
+</window>
+\end{lstlisting}
-- 
cgit v1.2.3