docs/wiki/geda-devel-tips.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
   2  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html>
   4 <head>
   5   <link rel="stylesheet" media="screen" type="text/css" href="./style.css" />
   6   <link rel="stylesheet" media="screen" type="text/css" href="./design.css" />
   7   <link rel="stylesheet" media="print" type="text/css" href="./print.css" />
   8
   9   <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  10 </head>
  11 <body>
  12
  13 <p>
  14 <em>Translations of this page are also available in the following languages:</em> <a href="geda-devel-tips.ru.html" class="wikilink1" title="geda-devel-tips.ru.html">Русский</a>.
  15 </p>
  16
  17 <h1 id="gedadevelopertipstricksandhints">gEDA Developer Tips, tricks and hints</h1>
  18 <div class="level1">
  19
  20 </div>
  21
  22 <h2 id="datastructureofaschematic">Data Structure of a Schematic</h2>
  23 <div class="level2">
  24
  25 <p>
  26 Internally, a schematic in gaf is implemented by number of doubly linked lists. The central type linked in the lists is OBJECT. It can represent a symbol, a line of text, a drawing primitive, a net, or an attribute.
  27 </p>
  28
  29 <p>
  30 An overview of the data structure of a schematic can be retrieved here. The sketch was drawn in 2005 by Stuart Brorson.
  31 </p>
  32
  33 </div>
  34
  35 <h2 id="doxygencommentsandstyles">Doxygen Comments and Styles</h2>
  36 <div class="level2">
  37
  38 <p>
  39 <strong>Doxygen</strong> is a tool which extracts API documentation from comments in the source code. Markup can be placed in the comments, which is then extracted and rendered to HTML or LaTeX by Doxygen. This allows e.g. one function to link to another related function, and permits arguments and return values to have documentation associated with them.
  40 </p>
  41
  42 <p>
  43 Some sections of the gaf source have already been doxyfied. Currently, this includes libgeda, gschem, gnetlist, gsymcheck and gattrib. The Makefile in the <em>docs</em> dir of these tools contains a target &quot;doxygen&quot;. Alternatively, you can browse the output of doxygen online on this site, made available by Bert Timmerman.
  44 </p>
  45
  46 <p>
  47 If you want to see Doxygen&#039;s ideas on how to format documentation see the Doxygen website. The individual commands are documented here. There is also a very handy Doxygen quick reference card.
  48 </p>
  49
  50 <p>
  51 The following sections provide an introduction on how gschem and libgeda are customarily documented. Note that the QT style of <strong>/*! comment goes here */</strong> for a Doxygen-enabled comment is preferred.
  52 </p>
  53
  54 </div>
  55
  56 <h3 id="documentingfiles">Documenting Files</h3>
  57 <div class="level3">
  58
  59 <p>
  60 When starting a new file, you obviously need to have the normal GNU license text.  After the GNU License you should include a file comment describing what the file is for and any other descriptions that apply to the whole file.
  61 </p>
  62 <pre class="code c">  <span class="coMULTI">/*! \file &lt;filename.ext&gt;
  63       \brief Put a brief summary of what this file is for...
  64       \par Description
  65       A lengthier description of what the file is for (this is optional).
  66    */</span></pre>
  67
  68 </div>
  69
  70 <h3 id="documentingvariablesdefinestypedefs">Documenting Variables/Defines/Typedefs</h3>
  71 <div class="level3">
  72
  73 <p>
  74 Global variables in a file can be documented using the <strong>\var</strong> command or by just writing a comment with a <strong>\brief</strong> command right before the definition.
  75 </p>
  76 <pre class="code c">  <span class="coMULTI">/*! \brief fill style of objects like cirle, rect, path */</span>
  77   <span class="kw4">typedef</span> <span class="kw2">enum</span> <span class="br0">&#123;</span>FILLING_HOLLOW<span class="sy0">,</span> FILLING_FILL<span class="sy0">,</span> FILLING_MESH<span class="sy0">,</span> FILLING_HATCH<span class="sy0">,</span> FILLING_VOID<span class="br0">&#125;</span> OBJECT_FILLING<span class="sy0">;</span></pre>
  78
  79 </div>
  80
  81 <h3 id="documentingfunctions">Documenting Functions</h3>
  82 <div class="level3">
  83
  84 <p>
  85 Functions can be documented in the same way as Variables, etc... Just use a comment block above the function it is documenting and use a <strong>\brief</strong> command to
  86 start it.
  87 </p>
  88
  89 <p>
  90 Usually an additional <strong>Function Description</strong> paragraph is used for the lengthy description of the function&#039;s purpose.
  91 Also <strong>\param</strong> commands are used with the [in] or [out] attributes to document if the parameter will be modified by the function.
  92 </p>
  93 <pre class="code c">  <span class="coMULTI">/*! \brief &quot;Save&quot; a file into a string buffer
  94    *  \par Function Description
  95    *  This function saves a whole schematic into a buffer in libgeda
  96    *  format. The buffer should be freed when no longer needed.
  97    *
  98    *  \param [in] toplevel    The current TOPLEVEL.
  99    *  \param [in] object_list The head of a GList of OBJECTs to save.
 100    *  \return a buffer containing schematic data or NULL on failure.
 101    */</span></pre>
 102
 103 </div>
 104
 105 <h3 id="structuredocumentation">Structure Documentation</h3>
 106 <div class="level3">
 107
 108 <p>
 109 Structures are documented the same as in the previous sections.  Note that comments on the structure members can be documented inline or using the same <strong>\brief</strong> syntax as variables.  Inline documentation requires the special comment starting with <strong>/*!&lt;</strong> at the end of the line it applies to.
 110 </p>
 111 <pre class="code c">  <span class="coMULTI">/*! \brief Structure for connections between OBJECTs
 112    *
 113    * The st_conn structure contains a single connection
 114    * to another object.
 115    * The connection system in s_conn.c uses this struct
 116    */</span>
 117   <span class="kw4">struct</span> st_conn <span class="br0">&#123;</span>
 118     OBJECT <span class="sy0">*</span>other_object<span class="sy0">;</span> <span class="coMULTI">/*!&lt; The &quot;other&quot; object connected to this one */</span>
 119     <span class="coMULTI">/*! \brief type of connection. Always in reference to how the &quot;other&quot;
 120         object is connected to the current one */</span>
 121     <span class="kw4">int</span> type<span class="sy0">;</span>
 122     <span class="kw4">int</span> x<span class="sy0">;</span> <span class="coMULTI">/*!&lt; x coord of the connection position */</span>
 123     <span class="kw4">int</span> y<span class="sy0">;</span> <span class="coMULTI">/*!&lt; y coord of the connection position */</span>
 124     <span class="kw4">int</span> whichone<span class="sy0">;</span> <span class="coMULTI">/*!&lt; which endpoint of the current object caused this connection */</span>
 125     <span class="kw4">int</span> other_whichone<span class="sy0">;</span> <span class="coMULTI">/*!&lt; which endpoint of the &quot;other&quot; object caused this connection */</span>
 126   <span class="br0">&#125;</span><span class="sy0">;</span></pre>
 127
 128 </div>
 129
 130 <h3 id="bugtodocommands">Bug/Todo Commands</h3>
 131 <div class="level3">
 132
 133 <p>
 134 <strong>\bug</strong> and <strong>\todo</strong> are useful for notating where there are defects or missing features in the code. These commands can be used anywhere within the Doxygen comments, and generate entries on special pages in the documentation so that they can easily be referred to.
 135 </p>
 136
 137 </div>
 138
 139 <h2 id="dialogsdesignandbehaviour">Dialogs: Design and Behaviour</h2>
 140 <div class="level2">
 141
 142 </div>
 143
 144 <h3 id="dialogdesign">Dialog Design</h3>
 145 <div class="level3">
 146
 147 <p>
 148 There&#039;s a nice document from the gnome guys called  Gnome HIG.
 149 There are several suggestions on how to design dialogs and how they should behave.
 150 </p>
 151
 152 <p>
 153 <strong> The dialog design is mostly a matter of taste:</strong>
 154 </p>
 155 <ul>
 156 <li class="level1"><div class="li"> alignment of elements. See  Window Layout</div>
 157 </li>
 158 <li class="level1"><div class="li"> right alignment of dialog buttons</div>
 159 </li>
 160 <li class="level1"><div class="li"> some spacing around the dialog (but how much?)</div>
 161 </li>
 162 <li class="level1"><div class="li"> some spacing between the elements (vertical and horizontal)</div>
 163 </li>
 164 <li class="level1"><div class="li"> option groups with frames or indentation?</div>
 165 </li>
 166 <li class="level1"><div class="li"> frame labels or bold headlines?</div>
 167 </li>
 168 </ul>
 169
 170 </div>
 171
 172 <h3 id="modalornonmodaldialogs">Modal or Nonmodal dialogs</h3>
 173 <div class="level3">
 174
 175 <p>
 176 A modal dialog is required whenever the main application provides data for the dialog.
 177 </p>
 178 <pre class="code">Example:
 179   The dialog is called with a selection list and the dialog only should operate on this selection.</pre>
 180
 181 <p>
 182 A modal dialog is OK too, if the dialog is only called very seldom. The file open dialog could be nonmodal because it does not require any input from the application.
 183 </p>
 184
 185 <p>
 186 A modal dialog is not OK if there is a lot of user interaction with the dialog. The component selection is a good example.
 187 </p>
 188
 189 </div>
 190
 191 <h3 id="wheretoplacethedialog">Where to place the dialog</h3>
 192 <div class="level3">
 193
 194 <p>
 195 A dialog can be put on different places in on the screen.
 196 A list of possible places can be found in the  GtkReference
 197 </p>
 198
 199 <p>
 200 The current dialogs are placed either on the mouse position (GTK_WIN_POS_MOUSE) or at no preset position (GTK_WIN_POS_NONE).
 201 The Gnome HID does not say anything about that topic.
 202 </p>
 203
 204 <p>
 205 The default setting is GTK_WIN_POS_NONE for GtkWindow see  GtkWindow.
 206 The default for GtkDialog is GTK_WIN_POS_CENTER_ON_PARENT ( taken from the GtkDialog source).
 207 </p>
 208
 209 </div>
 210
 211 <h3 id="placingdialogsinfrontoftheirparentwindow">Placing dialogs in front of their parent window</h3>
 212 <div class="level3">
 213
 214 <p>
 215 Most of the dialogs are placed in front of their parent window using the transient_for property (see.  GtkReference). This property should be set for all modal dialogs.
 216 </p>
 217
 218 <p>
 219 For nonmodal dialogs the setting of transient_for property is not obvious. While in gschem for example the coord dialog should stay above the parent window, the log window does not need to stay in front of it.
 220 </p>
 221
 222 <p>
 223 <strong>Note:</strong> There is an older mechanism that keeps the the dialogs in front of gschem. If the <em>raise-dialog-boxes-on-expose</em> variable is set to <em>enable</em> in one of gschem&#039;s configuration files, it may cause problems with some window managers.
 224 If dialogs are flickering at 100% CPU load, then disable that setting.
 225 </p>
 226 <pre class="code lisp"><span class="co1">; raise-dialog-boxes-on-expose string</span>
 227 <span class="co1">;</span>
 228 <span class="co1">; Controls if dialog boxes are raised whenever an expose event happens</span>
 229 <span class="co1">; Default is enabled</span>
 230 <span class="co1">;</span>
 231 <span class="co1">;(raise-dialog-boxes-on-expose &quot;enabled&quot;)</span>
 232 <span class="br0">&#40;</span>raise-dialog-boxes-on-expose <span class="st0">&quot;disabled&quot;</span><span class="br0">&#41;</span></pre>
 233
 234 </div>
 235
 236 <h3 id="buttonorderindialogs">Button order in dialogs</h3>
 237 <div class="level3">
 238
 239 <p>
 240 Button order at the bottom of the dialog depends on which operating system the user is using.
 241 GTK handles this automatically, but requires the developers set the alternative button order. For more information, check the GTK documentation here.
 242 </p>
 243
 244 <p>
 245 The alternative button order is set with just one call to a GTK function:
 246 </p>
 247 <pre class="code C"><span class="coMULTI">/* Set the alternative button order (ok, no, cancel, help) for other systems */</span>
 248 gtk_dialog_set_alternative_button_order<span class="br0">&#40;</span>GTK_DIALOG<span class="br0">&#40;</span>dialog<span class="br0">&#41;</span><span class="sy0">,</span>
 249                                         GTK_RESPONSE_OK<span class="sy0">,</span>
 250                                         GTK_RESPONSE_NO<span class="sy0">,</span>
 251                                         GTK_RESPONSE_CANCEL<span class="sy0">,</span>
 252                                         GTK_RESPONSE_HELP<span class="sy0">,</span>
 253                                         <span class="sy0">-</span><span class="nu0">1</span><span class="br0">&#41;</span><span class="sy0">;</span></pre>
 254
 255 <p>
 256 This should be done for every new dialog created, before running it.
 257 </p>
 258
 259 </div>
 260
 261 <h3 id="dialogdesignofthecurrentdialogs">Dialog design of the current dialogs</h3>
 262 <div class="level3">
 263
 264 <p>
 265 <a href="media/devel_tips/dialog_picture.png" class="media" target="_blank" title="devel_tips:dialog_picture.png">devel_tips:dialog_picture.png</a>
 266 </p>
 267 <ul>
 268 <li class="level1"><div class="li"> There is some space around the whole dialog (<em>DIALOG_BORDER_SPACING</em>).</div>
 269 </li>
 270 <li class="level1"><div class="li"> Some indentation to show the topic group (<em>DIALOG_INDENTATION</em>) below it&#039;s bold headline.</div>
 271 </li>
 272 <li class="level1"><div class="li"> The vertikal and the horizontal separation is done with <em>DIALOG_H_SPACING</em> and <em>DIALOG_V_SPACING</em>.</div>
 273 </li>
 274 </ul>
 275
 276 </div>
 277
 278 <h3 id="sourcetemplateforsimpledialogs">Source template for simple dialogs</h3>
 279 <div class="level3">
 280
 281 <p>
 282 This template is not intented to compile, but you can easily copy the code block that you need.
 283 </p>
 284 <pre class="code c"><span class="kw4">void</span> dialog <span class="br0">&#40;</span>TOPLEVEL <span class="sy0">*</span>w_current<span class="br0">&#41;</span>
 285 <span class="br0">&#123;</span>
 286   GtkWidget <span class="sy0">*</span>vbox<span class="sy0">,</span> <span class="sy0">*</span>label<span class="sy0">,</span> <span class="sy0">*</span>alignment<span class="sy0">,</span> <span class="sy0">*</span>table<span class="sy0">;</span>
 287   GtkWidget <span class="sy0">*</span>dialog<span class="sy0">;</span>
 288 &nbsp;
 289   <span class="coMULTI">/* only create the dialog if it is not there yet. This usually is a
 290      widget pointer in the w_current structure:
 291      dialog = w_current-&gt;tewindow */</span>
 292   <span class="kw1">if</span> <span class="br0">&#40;</span><span class="sy0">!</span>dialog<span class="br0">&#41;</span> <span class="br0">&#123;</span>
 293     dialog <span class="sy0">=</span> gtk_dialog_new_with_buttons<span class="br0">&#40;</span>_<span class="br0">&#40;</span><span class="st0">&quot;Dialog title&quot;</span><span class="br0">&#41;</span><span class="sy0">,</span>
 294                                          <span class="coMULTI">/* the parent window or NULL */</span>
 295                                          GTK_WINDOW<span class="br0">&#40;</span>w_current<span class="sy0">-&gt;</span>main_window<span class="br0">&#41;</span><span class="sy0">,</span>
 296                                          <span class="coMULTI">/* dialog properties */</span>
 297                                          GTK_DIALOG_MODAL<span class="sy0">,</span> <span class="coMULTI">/* 0 for nonmodal dialogs */</span>
 298                                          <span class="coMULTI">/* dialog buttons and response signals */</span>
 299                                          GTK_STOCK_CANCEL<span class="sy0">,</span>
 300                                          GTK_RESPONSE_REJECT<span class="sy0">,</span>
 301                                          GTK_STOCK_OK<span class="sy0">,</span>
 302                                          GTK_RESPONSE_ACCEPT<span class="sy0">,</span>
 303                                          NULL<span class="br0">&#41;</span><span class="sy0">;</span>
 304 &nbsp;
 305     <span class="coMULTI">/* Set the alternative button order (ok, no, cancel, help) for other systems */</span>
 306     gtk_dialog_set_alternative_button_order<span class="br0">&#40;</span>GTK_DIALOG<span class="br0">&#40;</span>dialog<span class="br0">&#41;</span><span class="sy0">,</span>
 307                                             GTK_RESPONSE_OK<span class="sy0">,</span>
 308                                             GTK_RESPONSE_NO<span class="sy0">,</span>
 309                                             GTK_RESPONSE_CANCEL<span class="sy0">,</span>
 310                                             GTK_RESPONSE_HELP<span class="sy0">,</span>
 311                                             <span class="sy0">-</span><span class="nu0">1</span><span class="br0">&#41;</span><span class="sy0">;</span>
 312 &nbsp;
 313     <span class="coMULTI">/* set default response signal. This is usually triggered by the
 314        &quot;Return&quot; key */</span>
 315     gtk_dialog_set_default_response<span class="br0">&#40;</span>GTK_DIALOG<span class="br0">&#40;</span>dialog<span class="br0">&#41;</span><span class="sy0">,</span>
 316                                     GTK_RESPONSE_ACCEPT<span class="br0">&#41;</span><span class="sy0">;</span>
 317 &nbsp;
 318     <span class="coMULTI">/* set the function for handling the button responses and dialog close
 319        for nonmodal dialogs you can use dialog_run() too.*/</span>
 320     gtk_signal_connect<span class="br0">&#40;</span>GTK_OBJECT<span class="br0">&#40;</span>dialog<span class="br0">&#41;</span><span class="sy0">,</span> <span class="st0">&quot;response&quot;</span><span class="sy0">,</span>
 321                        GTK_SIGNAL_FUNC<span class="br0">&#40;</span>dialog_response<span class="br0">&#41;</span><span class="sy0">,</span> w_current<span class="br0">&#41;</span><span class="sy0">;</span>
 322 &nbsp;
 323     <span class="coMULTI">/* where to place the dialog: GTK_WIN_POS_MOUSE or GTK_WIN_POS_NONE */</span>
 324     gtk_window_position<span class="br0">&#40;</span>GTK_WINDOW <span class="br0">&#40;</span>dialog<span class="br0">&#41;</span><span class="sy0">,</span> GTK_WIN_POS_MOUSE<span class="br0">&#41;</span><span class="sy0">;</span>
 325 &nbsp;
 326     <span class="coMULTI">/* set the border spacing and the vbox spacing of the dialog */</span>
 327     vbox <span class="sy0">=</span> GTK_DIALOG<span class="br0">&#40;</span>dialog<span class="br0">&#41;</span><span class="sy0">-&gt;</span>vbox<span class="sy0">;</span>
 328     gtk_container_set_border_width<span class="br0">&#40;</span>GTK_CONTAINER<span class="br0">&#40;</span>dialog<span class="br0">&#41;</span><span class="sy0">,</span>DIALOG_BORDER_SPACING<span class="br0">&#41;</span><span class="sy0">;</span>
 329     gtk_box_set_spacing<span class="br0">&#40;</span>GTK_BOX<span class="br0">&#40;</span>vbox<span class="br0">&#41;</span><span class="sy0">,</span> DIALOG_V_SPACING<span class="br0">&#41;</span><span class="sy0">;</span>
 330 &nbsp;
 331     <span class="coMULTI">/* create a label (with markup) and pack it into the dialog box */</span>
 332     label <span class="sy0">=</span> gtk_label_new<span class="br0">&#40;</span>_<span class="br0">&#40;</span><span class="st0">&quot;&lt;b&gt;Section label&lt;/b&gt;&quot;</span><span class="br0">&#41;</span><span class="br0">&#41;</span><span class="sy0">;</span>
 333     gtk_label_set_use_markup<span class="br0">&#40;</span>GTK_LABEL<span class="br0">&#40;</span>label<span class="br0">&#41;</span><span class="sy0">,</span> TRUE<span class="br0">&#41;</span><span class="sy0">;</span>
 334     gtk_misc_set_alignment<span class="br0">&#40;</span>GTK_MISC<span class="br0">&#40;</span>label<span class="br0">&#41;</span><span class="sy0">,</span><span class="nu0">0</span><span class="sy0">,</span><span class="nu0">0</span><span class="br0">&#41;</span><span class="sy0">;</span>
 335     gtk_box_pack_start<span class="br0">&#40;</span>GTK_BOX<span class="br0">&#40;</span>vbox<span class="br0">&#41;</span><span class="sy0">,</span> label<span class="sy0">,</span> FALSE<span class="sy0">,</span> FALSE<span class="sy0">,</span> <span class="nu0">0</span><span class="br0">&#41;</span><span class="sy0">;</span>
 336 &nbsp;
 337     <span class="coMULTI">/* create a alignment container with the DIALOG_INDENTATION on the left */</span>
 338     alignment <span class="sy0">=</span> gtk_alignment_new<span class="br0">&#40;</span><span class="nu0">0</span><span class="sy0">,</span><span class="nu0">0</span><span class="sy0">,</span><span class="nu0">1</span><span class="sy0">,</span><span class="nu0">1</span><span class="br0">&#41;</span><span class="sy0">;</span>
 339     gtk_alignment_set_padding<span class="br0">&#40;</span>GTK_ALIGNMENT<span class="br0">&#40;</span>alignment<span class="br0">&#41;</span><span class="sy0">,</span> <span class="nu0">0</span><span class="sy0">,</span> <span class="nu0">0</span><span class="sy0">,</span>
 340                               DIALOG_INDENTATION<span class="sy0">,</span> <span class="nu0">0</span><span class="br0">&#41;</span><span class="sy0">;</span>
 341     gtk_box_pack_start<span class="br0">&#40;</span>GTK_BOX<span class="br0">&#40;</span>vbox<span class="br0">&#41;</span><span class="sy0">,</span> alignment<span class="sy0">,</span> FALSE<span class="sy0">,</span> FALSE<span class="sy0">,</span> <span class="nu0">0</span><span class="br0">&#41;</span><span class="sy0">;</span>
 342 &nbsp;
 343     <span class="coMULTI">/* a table can store several entries. It is stored in the aligment container.
 344        Note: the vertical and horizontal cell spacings */</span>
 345     table <span class="sy0">=</span> gtk_table_new <span class="br0">&#40;</span><span class="nu0">3</span><span class="sy0">,</span> <span class="nu0">2</span><span class="sy0">,</span> FALSE<span class="br0">&#41;</span><span class="sy0">;</span>
 346     gtk_table_set_row_spacings<span class="br0">&#40;</span>GTK_TABLE<span class="br0">&#40;</span>table<span class="br0">&#41;</span><span class="sy0">,</span> DIALOG_V_SPACING<span class="br0">&#41;</span><span class="sy0">;</span>
 347     gtk_table_set_col_spacings<span class="br0">&#40;</span>GTK_TABLE<span class="br0">&#40;</span>table<span class="br0">&#41;</span><span class="sy0">,</span> DIALOG_H_SPACING<span class="br0">&#41;</span><span class="sy0">;</span>
 348     gtk_container_add<span class="br0">&#40;</span>GTK_CONTAINER<span class="br0">&#40;</span>alignment<span class="br0">&#41;</span><span class="sy0">,</span> table<span class="br0">&#41;</span><span class="sy0">;</span>
 349 &nbsp;
 350     <span class="coMULTI">/* a simple text label in one table cell with left alignment.
 351        Note: the GTK_FILL in the third line is required */</span>
 352     label <span class="sy0">=</span> gtk_label_new<span class="br0">&#40;</span>_<span class="br0">&#40;</span><span class="st0">&quot;Text:&quot;</span><span class="br0">&#41;</span><span class="br0">&#41;</span><span class="sy0">;</span>
 353     gtk_misc_set_alignment<span class="br0">&#40;</span>GTK_MISC<span class="br0">&#40;</span>label<span class="br0">&#41;</span><span class="sy0">,</span><span class="nu0">0</span><span class="sy0">,</span><span class="nu0">0</span><span class="br0">&#41;</span><span class="sy0">;</span>
 354     gtk_table_attach<span class="br0">&#40;</span>GTK_TABLE<span class="br0">&#40;</span>table<span class="br0">&#41;</span><span class="sy0">,</span> label<span class="sy0">,</span> <span class="nu0">0</span><span class="sy0">,</span><span class="nu0">1</span><span class="sy0">,</span><span class="nu0">0</span><span class="sy0">,</span><span class="nu0">1</span><span class="sy0">,</span> GTK_FILL<span class="sy0">,</span><span class="nu0">0</span><span class="sy0">,</span><span class="nu0">0</span><span class="sy0">,</span><span class="nu0">0</span><span class="br0">&#41;</span><span class="sy0">;</span>
 355 &nbsp;
 356     <span class="coMULTI">/* a simple text entry completes the option row */</span>
 357     textentry <span class="sy0">=</span> gtk_entry_new_with_max_length <span class="br0">&#40;</span><span class="nu0">10</span><span class="br0">&#41;</span><span class="sy0">;</span>
 358     gtk_table_attach_defaults<span class="br0">&#40;</span>GTK_TABLE<span class="br0">&#40;</span>table<span class="br0">&#41;</span><span class="sy0">,</span> textentry<span class="sy0">,</span> <span class="nu0">1</span><span class="sy0">,</span><span class="nu0">2</span><span class="sy0">,</span><span class="nu0">0</span><span class="sy0">,</span><span class="nu0">1</span><span class="br0">&#41;</span><span class="sy0">;</span>
 359     gtk_entry_set_activates_default<span class="br0">&#40;</span>GTK_ENTRY<span class="br0">&#40;</span>textentry<span class="br0">&#41;</span><span class="sy0">,</span> TRUE<span class="br0">&#41;</span><span class="sy0">;</span>
 360 &nbsp;
 361     <span class="coMULTI">/* ..... more table rows with options, or new sections */</span>
 362 &nbsp;
 363     <span class="coMULTI">/* create references to all widgets that you need later */</span>
 364     GLADE_HOOKUP_OBJECT<span class="br0">&#40;</span>dialog<span class="sy0">,</span> sizeentry<span class="sy0">,</span><span class="st0">&quot;textentry&quot;</span><span class="br0">&#41;</span><span class="sy0">;</span>
 365 &nbsp;
 366     <span class="coMULTI">/* show all widgets recursivly */</span>
 367     gtk_widget_show_all<span class="br0">&#40;</span>dialog<span class="br0">&#41;</span><span class="sy0">;</span>
 368   <span class="br0">&#125;</span>
 369 &nbsp;
 370   <span class="kw1">else</span> <span class="br0">&#123;</span>
 371     <span class="coMULTI">/* Dialog is already there. Present it to the user.
 372        This is only required if you have a nonmodal dialog */</span>
 373     gtk_window_present<span class="br0">&#40;</span>GTK_WINDOW<span class="br0">&#40;</span>dialog<span class="br0">&#41;</span><span class="br0">&#41;</span><span class="sy0">;</span>
 374   <span class="br0">&#125;</span>
 375 &nbsp;
 376   <span class="coMULTI">/* always set the current values to the dialog
 377      If you're placing that part at the end of the dialog function you can
 378      easily create dialogs that can be called, even if they are already open */</span>
 379   textentry <span class="sy0">=</span> g_object_get_data<span class="br0">&#40;</span>G_OBJECT<span class="br0">&#40;</span>dialog<span class="br0">&#41;</span><span class="sy0">,</span> <span class="st0">&quot;textentry&quot;</span><span class="br0">&#41;</span><span class="sy0">;</span>
 380   gtk_entry_set_text<span class="br0">&#40;</span>GTK_ENTRY<span class="br0">&#40;</span>textentry<span class="br0">&#41;</span><span class="sy0">,</span> string<span class="br0">&#41;</span><span class="sy0">;</span>
 381   <span class="coMULTI">/* select the text region that the user usually likes to overwrite */</span>
 382   gtk_entry_select_region<span class="br0">&#40;</span>GTK_ENTRY<span class="br0">&#40;</span>textentry<span class="br0">&#41;</span><span class="sy0">,</span> <span class="nu0">0</span><span class="sy0">,</span> <a href="http://www.opengroup.org/onlinepubs/009695399/functions/strlen.html"><span class="kw3">strlen</span></a><span class="br0">&#40;</span>string<span class="br0">&#41;</span><span class="br0">&#41;</span><span class="sy0">;</span>
 383 <span class="br0">&#125;</span></pre>
 384
 385 <p>
 386 The response function for such a dialog may look like this:
 387 </p>
 388 <pre class="code c"><span class="kw4">void</span> dialog_response<span class="br0">&#40;</span>GtkWidget <span class="sy0">*</span>widget<span class="sy0">,</span> gint response<span class="sy0">,</span> TOPLEVEL <span class="sy0">*</span>w_current<span class="br0">&#41;</span>
 389 <span class="br0">&#123;</span>
 390   <span class="kw1">switch</span> <span class="br0">&#40;</span>response<span class="br0">&#41;</span> <span class="br0">&#123;</span>
 391   <span class="kw1">case</span> GTK_RESPONSE_ACCEPT<span class="sy0">:</span>
 392     <span class="coMULTI">/* apply the dialog settings:
 393        just insert your code here if it is short
 394        call an extra apply function if the required code is long */</span>
 395     <span class="kw2">break</span><span class="sy0">;</span>
 396   <span class="kw1">case</span> GTK_RESPONSE_REJECT<span class="sy0">:</span>
 397   <span class="kw1">case</span> GTK_RESPONSE_DELETE_EVENT<span class="sy0">:</span>
 398     <span class="coMULTI">/* for modal dialogs just do nothing,
 399        for nonmodal dialogs, destroy the dialog and clean up */</span>
 400     <span class="kw2">break</span><span class="sy0">;</span>
 401   <span class="kw1">default</span><span class="sy0">:</span>
 402     <span class="coMULTI">/* catch wrong signals signals (paranoid error checking ;-)) */</span>
 403     <a href="http://www.opengroup.org/onlinepubs/009695399/functions/printf.html"><span class="kw3">printf</span></a><span class="br0">&#40;</span><span class="st0">&quot;dialog_response(): strange signal %d<span class="es1">\n</span>&quot;</span><span class="sy0">,</span> response<span class="br0">&#41;</span><span class="sy0">;</span>
 404   <span class="br0">&#125;</span>
 405 &nbsp;
 406   <span class="coMULTI">/* for nonmodal dialogs just do nothing,
 407      for modal dialogs, always destroy the dialog and clean up */</span>
 408 <span class="br0">&#125;</span></pre>
 409
 410 </div>
 411
 412 <h3 id="currentdialogissuesingschem">Current Dialog Issues in Gschem</h3>
 413 <div class="level3">
 414 <ul>
 415 <li class="level1"><div class="li"> every dialog has it&#039;s own design</div>
 416 </li>
 417 <li class="level1"><div class="li"> dialog placement: mouse position or no predefined position?</div>
 418 </li>
 419 <li class="level1"><div class="li"> dialogs do not remember their last size, position and contents.</div>
 420 </li>
 421 <li class="level1"><div class="li"> missing keyboard shortcuts</div>
 422 </li>
 423 </ul>
 424
 425 <p>
 426 <strong>Here&#039;s a list of things that could be improved:</strong>
 427 </p>
 428
 429 </div>
 430
 431 <h5 id="printdialog">Print Dialog</h5>
 432 <div class="level5">
 433 <ul>
 434 <li class="level1"><div class="li"> change design?</div>
 435 </li>
 436 </ul>
 437
 438 </div>
 439
 440 <h5 id="writeimage">Write Image</h5>
 441 <div class="level5">
 442 <ul>
 443 <li class="level1"><div class="li"> In the fileselect dialog the default filename is missing if the file does not exist</div>
 444 </li>
 445 <li class="level1"><div class="li"> Return key does not work in the filename entry</div>
 446 </li>
 447 </ul>
 448
 449 </div>
 450
 451 <h5 id="executescript">Execute Script</h5>
 452 <div class="level5">
 453 <ul>
 454 <li class="level1"><div class="li"></div>
 455 </li>
 456 </ul>
 457
 458 </div>
 459
 460 <h5 id="edittext">Edit Text</h5>
 461 <div class="level5">
 462 <ul>
 463 <li class="level1"><div class="li"> some missing keyboard shortcuts</div>
 464 </li>
 465 <li class="level1"><div class="li"> add *unmodified* tags if there are multiple selections</div>
 466 </li>
 467 <li class="level1"><div class="li"> maybe add some color pixbufs for the color</div>
 468 </li>
 469 <li class="level1"><div class="li"> maybe replace the text alignment with nine ratio buttons, toggle buttons with icons or ...</div>
 470 </li>
 471 </ul>
 472
 473 </div>
 474
 475 <h5 id="colordialog">Color Dialog</h5>
 476 <div class="level5">
 477 <ul>
 478 <li class="level1"><div class="li"> maybe add some color pixbufs for the color</div>
 479 </li>
 480 </ul>
 481
 482 </div>
 483
 484 <h5 id="linewidthandtype">Line Width and Type</h5>
 485 <div class="level5">
 486 <ul>
 487 <li class="level1"><div class="li"> keyboard shortcuts missing</div>
 488 </li>
 489 <li class="level1"><div class="li"> icons for the line type</div>
 490 </li>
 491 </ul>
 492
 493 </div>
 494
 495 <h5 id="filltype">Fill Type</h5>
 496 <div class="level5">
 497 <ul>
 498 <li class="level1"><div class="li"> keyboard shortcuts missing</div>
 499 </li>
 500 <li class="level1"><div class="li"> icons in the fill type</div>
 501 </li>
 502 </ul>
 503
 504 </div>
 505
 506 <h5 id="translatesymbol">Translate Symbol</h5>
 507 <div class="level5">
 508 <ul>
 509 <li class="level1"><div class="li"></div>
 510 </li>
 511 </ul>
 512
 513 </div>
 514
 515 <h5 id="pagemanager">Page Manager</h5>
 516 <div class="level5">
 517 <ul>
 518 <li class="level1"><div class="li"> wrong button order? Depends on whether you think the refresh button is the main action button or just an extra button.</div>
 519 </li>
 520 <li class="level1"><div class="li"> Maybe the &quot;Return&quot; key should trigger Refresh</div>
 521 </li>
 522 </ul>
 523
 524 </div>
 525
 526 <h5 id="componentselector">Component Selector</h5>
 527 <div class="level5">
 528 <ul>
 529 <li class="level1"><div class="li"> strange edit widget when typing and the tree is selected (It&#039;s a search helper widget, disable it?!)</div>
 530 </li>
 531 </ul>
 532
 533 </div>
 534
 535 <h5 id="singleattributeditor">Single Attribut Editor</h5>
 536 <div class="level5">
 537 <ul>
 538 <li class="level1 node"><div class="li"> when multiple elements are selected and you call edit (ee) there are a few problems:</div>
 539 <ul>
 540 <li class="level3"><div class="li"> if the first object is text, then this dialog is opened (but with the wrong list parameter</div>
 541 </li>
 542 <li class="level3"><div class="li"> if the first object is complex then the multiple attribute editor is called</div>
 543 </li>
 544 </ul>
 545 </li>
 546 </ul>
 547
 548 </div>
 549
 550 <h5 id="multiattributeeditor">Multi Attribute Editor</h5>
 551 <div class="level5">
 552 <ul>
 553 <li class="level1"><div class="li"></div>
 554 </li>
 555 </ul>
 556
 557 </div>
 558
 559 <h5 id="addtext">Add Text</h5>
 560 <div class="level5">
 561 <ul>
 562 <li class="level1"><div class="li"></div>
 563 </li>
 564 </ul>
 565
 566 </div>
 567
 568 <h5 id="arcparams">Arc Params</h5>
 569 <div class="level5">
 570 <ul>
 571 <li class="level1"><div class="li"> add the diameter to the dialog, but select the start angle entry (increment = grid)</div>
 572 </li>
 573 <li class="level1"><div class="li"> let &quot;ee&quot; call that dialog if only a single arc is selected</div>
 574 </li>
 575 <li class="level1"><div class="li"> maybe add a section label</div>
 576 </li>
 577 </ul>
 578
 579 </div>
 580
 581 <h5 id="insertpicture">Insert Picture</h5>
 582 <div class="level5">
 583 <ul>
 584 <li class="level1"><div class="li"></div>
 585 </li>
 586 </ul>
 587
 588 </div>
 589
 590 <h5 id="picturereplace">Picture Replace</h5>
 591 <div class="level5">
 592 <ul>
 593 <li class="level1"><div class="li"> the new picture uses the aspect ratio of the old picture</div>
 594 </li>
 595 <li class="level1"><div class="li"> the dialog has lots in common with the Insert Picture dialog. They could use some code together</div>
 596 </li>
 597 </ul>
 598
 599 </div>
 600
 601 <h5 id="findtext">Find Text</h5>
 602 <div class="level5">
 603 <ul>
 604 <li class="level1"><div class="li"> manipulates the mouse pointer (maybe the zooming code is the culprit). Just press &quot;Return&quot; to trigger a FindNext</div>
 605 </li>
 606 <li class="level1"><div class="li"> if you select hierarchy and the found text is in a different schematic, then the filename in the title is not updated</div>
 607 </li>
 608 <li class="level1"><div class="li"> maybe add an option: &quot;Select all matching text objects&quot;, disable hierarchy for that feature!</div>
 609 </li>
 610 <li class="level1"><div class="li"> FIXME gschem hangs if you use that dialog with hierarchical schematics that have dependancy loops (e.g. the autonumber test schematics)</div>
 611 </li>
 612 <li class="level1"><div class="li"> add an option &quot;search for visible text only&quot;</div>
 613 </li>
 614 <li class="level1"><div class="li"> maybe use regular expressions instead of the substring for the searchtext</div>
 615 </li>
 616 </ul>
 617
 618 </div>
 619
 620 <h5 id="hidetext">Hide Text</h5>
 621 <div class="level5">
 622 <ul>
 623 <li class="level1"><div class="li"> use regular expressions instead of starting substring</div>
 624 </li>
 625 </ul>
 626
 627 </div>
 628
 629 <h5 id="showtext">Show Text</h5>
 630 <div class="level5">
 631 <ul>
 632 <li class="level1"><div class="li"> use regular expressions instead of starting substring</div>
 633 </li>
 634 <li class="level1"><div class="li"> Maybe merge that dialog together with the &quot;Hide Text&quot; dialog</div>
 635 </li>
 636 </ul>
 637
 638 </div>
 639
 640 <h5 id="autonumbertext">Autonumber Text</h5>
 641 <div class="level5">
 642 <ul>
 643 <li class="level1"><div class="li"> Maybe disable the skip option if the renumber scope is &quot;selection&quot;. The other skip options (Page and Hierarchy) are really stupid.</div>
 644 </li>
 645 </ul>
 646
 647 </div>
 648
 649 <h5 id="textsize">Text Size</h5>
 650 <div class="level5">
 651 <ul>
 652 <li class="level1"><div class="li"></div>
 653 </li>
 654 </ul>
 655
 656 </div>
 657
 658 <h5 id="snapgridspacing">Snap Grid Spacing</h5>
 659 <div class="level5">
 660 <ul>
 661 <li class="level1"><div class="li"></div>
 662 </li>
 663 </ul>
 664
 665 </div>
 666
 667 <h5 id="coorddialog">Coord Dialog</h5>
 668 <div class="level5">
 669 <ul>
 670 <li class="level1"><div class="li"> maybe move the world coordinates to the main window status bar</div>
 671 </li>
 672 </ul>
 673
 674 </div>
 675
 676 <h5 id="aboutdialog">About Dialog</h5>
 677 <div class="level5">
 678 <ul>
 679 <li class="level1"><div class="li"></div>
 680 </li>
 681 </ul>
 682
 683 </div>
 684
 685 <h5 id="hotkeys">Hotkeys</h5>
 686 <div class="level5">
 687 <ul>
 688 <li class="level1"><div class="li"></div>
 689 </li>
 690 </ul>
 691
 692 </div>
 693 </body>
 694 </html>