home *** CD-ROM | disk | FTP | other *** search
/ PCNET 2006 September - Disc 1 / PCNET_CD_2006_09.iso / linux / puppy-barebones-2.01r2.iso / pup_201.sfs / usr / share / doc / gtkdialog2.txt < prev    next >
Encoding:
GNU Info File  |  2005-07-29  |  18.3 KB  |  609 lines
  1. This is gtkdialog.info, produced by makeinfo version 4.8 from
  2. gtkdialog.texi.
  3.  
  4.    This manual documents version {No value for `VERSION'} of the
  5. Gtkdialog utility.
  6.  
  7.    Copyright (C) 2003 Laszlo Pere.
  8.  
  9.      Permission is granted to copy, distribute and/or modify this
  10.      document under the terms of the GNU Free Documentation License,
  11.      Version 1.1 or any later version published by the Free Software
  12.      Foundation; with no Invariant Sections, with no Front-Cover Texts,
  13.      and with no Back-Cover Texts.
  14.  
  15. 
  16. File: gtkdialog.info,  Node: Top,  Next: Getting Gtkdialog,  Up: (dir)
  17.  
  18. Gtkdialog User's Manual
  19. ***********************
  20.  
  21. This manual documents version {No value for `VERSION'} of the Gtkdialog
  22. utility.
  23.  
  24.    Copyright (C) 2003 Laszlo Pere.
  25.  
  26.      Permission is granted to copy, distribute and/or modify this
  27.      document under the terms of the GNU Free Documentation License,
  28.      Version 1.1 or any later version published by the Free Software
  29.      Foundation; with no Invariant Sections, with no Front-Cover Texts,
  30.      and with no Back-Cover Texts.
  31.  
  32. * Menu:
  33.  
  34. * Getting Gtkdialog::      How to find, download and install the program.
  35. * Introduction::           A brief description of the package.
  36. * Invoking the Program::   How to call the program from various languages.
  37. * Widgets::               The elements of dialog boxes.
  38. * Containers::           Dialog elements grouping widgets together.
  39. * Actions::           What is happening when something happening.
  40.  
  41. 
  42. File: gtkdialog.info,  Node: Getting Gtkdialog,  Next: Introduction,  Prev: Top,  Up: Top
  43.  
  44. 1 Getting Gtkdialog
  45. *******************
  46.  
  47. 1.1 Download
  48. ============
  49.  
  50. The source of Gtkdialog can be downloaded from Anonymous FTP at URL
  51. `ftp://linux.pte.hu/pub/gtkdialog/'.
  52.  
  53. 1.2 How to Install the Program
  54. ==============================
  55.  
  56. The program can be installed using the standard `./configure', `make'
  57. and `make install' command sequence. Further details can be found in
  58. the `INSTALL' file included.
  59.  
  60. 1.3 Copying
  61. ===========
  62.  
  63. Copyright (C) 2003 Laszlo Pere.
  64.  
  65.    The gtkdialog is free software; you can redistribute it and/or
  66. modify it under the terms of the GNU General Public License as
  67. published by the Free Software Foundation; either version 2.0 of the
  68. License, or (at your option) any later version.
  69.  
  70.    The program is distributed in the hope that it will be useful, but
  71. WITHOUT ANY WARRANTY; without even the implied warranty of
  72. MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  73. General Public License for more details.
  74.  
  75.    You should have received a copy of the GNU General Public License
  76. along with this software; if not, write to the Free Software
  77. Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307,
  78. USA.
  79.  
  80. 
  81. File: gtkdialog.info,  Node: Introduction,  Next: Invoking the Program,  Prev: Getting Gtkdialog,  Up: Top
  82.  
  83. 2 Introduction
  84. **************
  85.  
  86. Gtkdialog is a small utility program based on the GTK+ library. The
  87. program mainly made for GUI development for shell scripts but can be
  88. used with many other programming languages. The programmer can easily
  89. create GUI not just for any shell script or UNIX command but for any
  90. interpreted or compiled program capable to start child process and use
  91. pipes.
  92.  
  93. 
  94. File: gtkdialog.info,  Node: Invoking the Program,  Next: Widgets,  Prev: Introduction,  Up: Top
  95.  
  96. 3 Invoking the Program
  97. **********************
  98.  
  99. 3.1 Examples
  100. ============
  101.  
  102. Our first example program shows how to call the `gtkdialog' from a BASH
  103. script.
  104.  
  105.      #! /bin/bash
  106.  
  107.      export MAIN_DIALOG='
  108.       <vbox>
  109.        <text>
  110.          <label>This is a label...</label>
  111.        </text>
  112.        <hbox>
  113.         <button ok></button>
  114.         <button cancel></button>
  115.        </hbox>
  116.       </vbox>'
  117.  
  118.      gtkdialog --program MAIN_DIALOG
  119.  
  120.    This example uses a very plain way to open a dialog box. We store the
  121. description of the dialog box in the `MAIN_DIALOG' environment variable
  122. which is exported to the child processes with the BASH `export'
  123. built-in. Then we call the `gtkdialog' program with the `--program'
  124. option which is followed by the name of the variable holding the dialog
  125. box description. It is simple and easy to write BASH scripts in this
  126. manner.
  127.  
  128.    A similar calling method can be used when user input is needed. The
  129. `gtkdialog' send the state of the widgets to the standard output when
  130. exiting and this is how we can get user input for the BASH program. The
  131. next example code show the reading process.
  132.      #! /bin/bash
  133.  
  134.      export DIALOG='
  135.      <vbox>
  136.        <entry>
  137.          <variable>ENTRY</variable>
  138.        </entry>
  139.        <hbox>
  140.          <button ok></button>
  141.          <button cancel></button>
  142.        </hbox>
  143.      </vbox>'
  144.  
  145.      I=$IFS; IFS=""
  146.      for STATEMENTS in  $(gtkdialog --program DIALOG); do
  147.        eval $STATEMENTS
  148.      done
  149.      IFS=$I
  150.  
  151.      if [ "$EXIT" = "OK" ]; then
  152.        echo "You entered: $ENTRY."
  153.      else
  154.        echo "You pressed the Cancel button."
  155.      fi
  156.  
  157.    In the example script we use the `for' built-in to go through the
  158. list `gtkdialog' produced. Changing the field separator (IFS) is a
  159. little bit disturbing but necessary since this is the only way to
  160. protect the space characters in user input.
  161.  
  162.    In larger software projects it may be a good idea to break the code
  163. to separate files. Since `gtkdialog' can read the description program
  164. from file it is easy to write self executable programs with it. This is
  165. how the next example constructed.
  166.  
  167.      #! /usr/local/bin/gtkdialog -f
  168.      <vbox>
  169.        <checkbox>
  170.          <label>This is a checkbox</label>
  171.          <variable>CHECK1</variable>
  172.        </checkbox>
  173.        <checkbox>
  174.          <label>Another one</label>
  175.          <variable>CHECK2</variable>
  176.        </checkbox>
  177.        <button>
  178.          <label>OK</label>
  179.        </button>
  180.      </vbox>
  181.  
  182.    When used in this fashion the state of the widgets can get from the
  183. standard output of the script as usually.
  184.  
  185. 
  186. File: gtkdialog.info,  Node: Widgets,  Next: Containers,  Prev: Invoking the Program,  Up: Top
  187.  
  188. 4 Widgets
  189. *********
  190.  
  191. The dialog description language is a simple XML like language capable
  192. to denote any complex dialog box containing widgets and boxes.
  193.  
  194.    Widgets are simple GUI elements such as buttons, entry fields, lists,
  195. etc. Widget can have attributes, states and actions (*note Actions::).
  196.  
  197.    The widgets are grouped together with containers (*note
  198. Containers::), horizontal and vertical boxes or frames. Every widget
  199. should placed in one of the containers, no widgets can be alone for it
  200. is dangerous outside.
  201.  
  202. * Menu:
  203.  
  204. * Static label::                Labels containing static text
  205. * Pushbutton::            Pushbutton widgets
  206. * Pre-defined pushbuttons::    Pushbuttons with pixmap and text label
  207. * Entry::            One line text entry widgets
  208. * Checkbox::            Checkbox widgets
  209. * Pixmap::            Static pixmap widgets
  210. * Menus::                       Making menubars, menus and menuitems
  211. * Trees::                       Complex widget for trees
  212.  
  213. 
  214. File: gtkdialog.info,  Node: Static label,  Next: Pushbutton,  Up: Widgets
  215.  
  216. 4.1 Static label
  217. ================
  218.  
  219. Label is a static text widget created with `<text></text>' tag.
  220.  
  221.    The text in a static label, can be set with the
  222. `<label>STRING</label>' or the `<input file>FILENAME</input>'
  223. expression.
  224.  
  225. 
  226. File: gtkdialog.info,  Node: Pushbutton,  Next: Pre-defined pushbuttons,  Prev: Static label,  Up: Widgets
  227.  
  228. 4.2 Pushbutton
  229. ==============
  230.  
  231. The pushbutton is a clickable widget defined with the
  232. `<button></button>' tags.
  233.  
  234. 4.2.1 `<label></label>'
  235. -----------------------
  236.  
  237. The `<label>STRING</label>' directive sets the text label of the
  238. pushbutton. If no label and pixmap is given for the button, gtkdialog
  239. will use OK as default.
  240.  
  241. 4.2.2 `<input file></input>'
  242. ----------------------------
  243.  
  244. When creating buttons, the `<input file>FILENAME</input>' tag can be
  245. used to insert a pixmap into the button. The FILENAME must be a pixmap
  246. file. Gtkdialog will find this file with the `locate' utility if
  247. necessary.
  248.  
  249.    The pushbuttons can contain a label and a pixmap simultaneously. For
  250. this you have to use the `<label></label>' and the `<input
  251. file></input>' as the next example shows:
  252.  
  253.      <button>
  254.        <input file>/usr/share/GUIcompletion/button_save.xpm</input>
  255.        <label>The label</label>
  256.      </button>
  257.  
  258. 4.2.3 `<action></action>'
  259. -------------------------
  260.  
  261. The `<action>COMMAND</action>' directive tells the gtkdialog what to
  262. do, when the button is pressed. If the action is not given explicitly
  263. the gtkdialog uses the default action, which is to exit the program. In
  264. this case the printed variable list will contain a variable named EXIT,
  265. with the label of the activated button as value.
  266.  
  267.    The buttons can handle more than one actions simultaneously. If there
  268. are more `<action></action>' directive for the given button, they will
  269. be executed one by one, in the right order.
  270.  
  271. 4.2.4 `<visible></visible>'
  272. ---------------------------
  273.  
  274. The `<visible>STATE</visible>' specify the initial visibility of the
  275. button. The STATE can be either `enabled' or `disabled'. When a button
  276. is disabled, it is shaded and can not be activated by mouse or keyboard.
  277.  
  278. 
  279. File: gtkdialog.info,  Node: Pre-defined pushbuttons,  Next: Entry,  Prev: Pushbutton,  Up: Widgets
  280.  
  281. 4.3 Pre-defined pushbuttons
  282. ===========================
  283.  
  284. Gtkdialog supports a few pre-defined pushbuttons for simplify the
  285. creation of dialog boxes. The pre-defined buttons can be used the same
  286. manner the normal pushbuttons, but they have a default text, pixmap and
  287. output variable.  Here is the list of available pre-defined pushbuttons:
  288.  
  289.    * `<button ok></button>'
  290.  
  291.    * `<button cancel></button>'
  292.  
  293.    * `<button help></button>'
  294.  
  295.    * `<button yes></button>'
  296.  
  297.    * `<button no></button>'
  298.  
  299. 
  300. File: gtkdialog.info,  Node: Entry,  Next: Checkbox,  Prev: Pre-defined pushbuttons,  Up: Widgets
  301.  
  302. 4.4 Entry
  303. =========
  304.  
  305. The entry widget is a simple text input field, which can be used to get
  306. a string from the user.
  307.  
  308. 4.4.1 `<default></default>'
  309. ---------------------------
  310.  
  311. The `<default>STRING</default>' directive sets the default content of
  312. the entry.
  313.  
  314. 4.4.2 `<visible></visible>'
  315. ---------------------------
  316.  
  317. The `<visible>VISIBILITY</visible>' sets the initial state of the entry
  318. widget. The VISIBILITY can be `enabled', which means the entry can be
  319. used, `disabled', which means the content of the entry can not be
  320. altered or `password'.
  321.  
  322.    The entry widgets with the visibility set to `password' are
  323. editable, but unreadable as it is common with entries holding password
  324. style information.
  325.  
  326. 4.4.3 `<action></action>'
  327. -------------------------
  328.  
  329. The entry widgets are activating actions after their contents are
  330. changed.
  331.  
  332. 
  333. File: gtkdialog.info,  Node: Checkbox,  Next: Pixmap,  Prev: Entry,  Up: Widgets
  334.  
  335. 4.5 Checkbox
  336. ============
  337.  
  338. The checkbox is a simple widget with a label and a check mark which can
  339. be turned on and off by the user. Checkboxes are made with the
  340. `<checkbox></checkbox>' directive.
  341.  
  342. 4.5.1 `<label></label>'
  343. -----------------------
  344.  
  345. The label is the text shown beside the check mark. Every checkbox
  346. should have a label.
  347.  
  348. 4.5.2 `<default></default>'
  349. ---------------------------
  350.  
  351. The initial state of the checkbox can be set by the
  352. `<default>STATE</default>' directive, where the STATE can be either
  353. `yes' or `no'.
  354.  
  355. 4.5.3 `<action></action>'
  356. -------------------------
  357.  
  358. The `<action></action>' directive tells the gtkdialog what to do, when
  359. the state of the checkbox is changed. As every widgets, the checkbox
  360. can hold multiply actions which are executed serially in the order they
  361. are written.
  362.  
  363.    Actions of checkboxes can be written as conditional instructions with
  364. `if true' and `if false' prefixes as in the next example:
  365.  
  366.      <checkbox>
  367.          <label>This is a checkbox...</label>
  368.          <variable>CHECKBOX</variable>
  369.          <action>echo Checkbox is $CHECKBOX now.</action>
  370.          <action>if true enable:ENTRY</action>
  371.          <action>if false disable:ENTRY</action>
  372.      </checkbox>
  373.  
  374. 4.5.4 `<visible></visible>'
  375. ---------------------------
  376.  
  377. The `<visible>STATE</visible>' specify the initial visibility of the
  378. checkbox. The STATE can be either `enabled' or `disabled'. When a
  379. checkbox is disabled, it is shaded and its state can not be altered
  380. anyway.
  381.  
  382. 4.5.5 `<variable></variable>'
  383. -----------------------------
  384.  
  385. The value of a checkbox can be `true' or `false' and depends only on
  386. its state.
  387.  
  388. 
  389. File: gtkdialog.info,  Node: Pixmap,  Next: Menus,  Prev: Checkbox,  Up: Widgets
  390.  
  391. 4.6 Pixmap
  392. ==========
  393.  
  394. The `<pixmap></pixmap>' defines a static pixmap widget.
  395.  
  396. 4.6.1 `<input file></input>'
  397. ----------------------------
  398.  
  399. The widget must have an input file defined with the `<input
  400. file>FILENAME</input>' tags. The FILENAME is the graphic image file for
  401. the pixmap. Gtkdialog will load this file if it can be opened for read,
  402. or will try to find a file with similar name (using the `locate'
  403. utility program) if the file is unreadable.
  404.  
  405.    The next example defines a static pixmap:
  406.  
  407.      <pixmap>
  408.        <input file>help.png</input>
  409.      </pixmap>
  410.  
  411. 
  412. File: gtkdialog.info,  Node: Menus,  Next: Trees,  Prev: Pixmap,  Up: Widgets
  413.  
  414. 4.7 Menubar
  415. ===========
  416.  
  417. The `<menubar></menubar>' defines menu bar which can be placed as any
  418. other screen elements. In the menubar widget you have to create menus
  419. with the `<menu></menu>' tag, and inside the menu must be at least one
  420. menu item created by the `<menuitem></menuitem>' tag.
  421.  
  422.    The next example shows how to create a simple menubar with only one
  423. menu:
  424.  
  425.      <menubar>
  426.        <menu>
  427.          <menuitem>
  428.            <label>gtk-open</label>
  429.          </menuitem>
  430.          <menuitem>
  431.            <label>gtk-save</label>
  432.          </menuitem>
  433.          <menuitem>
  434.            <label>gtk-quit</label>
  435.            <action>EXIT="quit"</action>
  436.          </menuitem>
  437.          <label>File</label>
  438.        </menu>
  439.      </menubar>
  440.  
  441. 
  442. File: gtkdialog.info,  Node: Trees,  Prev: Menus,  Up: Widgets
  443.  
  444. 4.8 The tree
  445. ============
  446.  
  447. OK, it is not complete, but the next example seems to be just fine.
  448.  
  449.      <vbox>
  450.        <tree>
  451.          <label>Device    |Directory        |File         </label>
  452.          <item>Hard drive |/usr/            |letter.tex    </item>
  453.          <item>Hard drive |/etc/            |inittab       </item>
  454.          <item>Hard drive |/etc/            |fstab         </item>
  455.          <item>Network    |alpha:/home      |quota.user    </item>
  456.          <item>Network    |alpha:/home      |quota.group   </item>
  457.          <item>Network    |beta:/home/pipas |tmp           </item>
  458.          <item>Network    |beta:/home/pipas |latexfiles    </item>
  459.          <item>Network    |beta:/home/pipas |book          </item>
  460.          <item>Network    |beta:/home/pipas |bin           </item>
  461.          <item>Network    |beta:/home/pipas |documentation </item>
  462.        </tree>
  463.        <button ok></button>
  464.      </vbox>
  465.  
  466. 
  467. File: gtkdialog.info,  Node: Containers,  Next: Actions,  Prev: Widgets,  Up: Top
  468.  
  469. 5 Containers
  470. ************
  471.  
  472. 
  473. File: gtkdialog.info,  Node: Actions,  Prev: Containers,  Up: Top
  474.  
  475. 6 Actions
  476. *********
  477.  
  478. When the user changes the state of a widget, gtkdialog checks if there
  479. is something to do with it. If the tampered widget have one or more
  480. actions, the program will execute them for the new situation to be
  481. handled.
  482.  
  483.    Every widget can have multiply actions, a list of commands must be
  484. executed when the widget changed. Gtkdialog executes the axtions in the
  485. order they found in the dialog description program, so one can write a
  486. complet program as a series of instructions.
  487.  
  488. * Menu:
  489.  
  490. * Start and exit::    Actions that starts programs and exits dialogs
  491. * Widget manipulation:: Actions affect widgets
  492.  
  493. 
  494. File: gtkdialog.info,  Node: Start and exit,  Next: Widget manipulation,  Up: Actions
  495.  
  496. 6.1 Start and exit
  497. ==================
  498.  
  499. 6.1.1 Start programs
  500. --------------------
  501.  
  502. If the action of a widget is created with the simple
  503. `<action>COMMAND</action>' directive, gtkdialog will execute it in a
  504. subshell. That means it will start up `/bin/sh' to handle the
  505. operation. Here is how the subshell operation works:
  506.   1. First gtkdialog updates the environment variables holds the  state
  507.      and value of the widgets. This is how the child process will  know
  508.      what is happening in the GUI called it.
  509.  
  510.   2. Next the include file is checked. If the gtkdialog started  with
  511.      the `-i FILE' option gtkdialog will ask the  subshell to include
  512.      the FILE before the execution of command.
  513.  
  514.      This strange method is needed for the action driven programs, where
  515.      the subshell have to load the shell functions from the calling
  516.      script.
  517.  
  518.   3. At the third step gtkdialog starts the command and waits for  it
  519.      to complete. (Commands usually can be run in the background by
  520.      writing a `&' as last character, so the subshell will not wait
  521.      the program to complete.)
  522.  
  523. 6.1.2 Exit dialog
  524. -----------------
  525.  
  526. The `Exit:VALUE' command exits `gtkdialog' immediately. The VALUE will
  527. be printed to standard output as the value of the variable named EXIT.
  528.  
  529. 
  530. File: gtkdialog.info,  Node: Widget manipulation,  Prev: Start and exit,  Up: Actions
  531.  
  532. 6.2 Widget manipulation
  533. =======================
  534.  
  535. 6.2.1 `Closewindow:NAME'
  536. ------------------------
  537.  
  538. The command closes the named window opened by the `Launch:' command.
  539. The program remain active if there are more windows active.
  540.  
  541. 6.2.2 `Launch:NAME'
  542. -------------------
  543.  
  544. The command opens a new window using the environment variable `Widget'.
  545.  
  546. 6.2.3 `Disable:NAME'
  547. --------------------
  548.  
  549. The command disables the given widget if it is enabled. If the widget
  550. is disabled when the command is activated, nothing happens.
  551.  
  552.    The disabled widgets are insensitive to user actions, their shapes
  553. are indicating they are temporary unavailable.
  554.  
  555. 6.2.4 `Enable:NAME'
  556. -------------------
  557.  
  558. The command enables the given widget if it is diabled. If the widget is
  559. enabled nothing happens.
  560.  
  561. 6.2.5 `Refresh:NAME'
  562. --------------------
  563.  
  564. The command refresh the named widget. If the widget have one or more
  565. input actions, they will be called by `gtkdialog'.
  566.  
  567. 6.2.6 `Save:NAME'
  568. -----------------
  569.  
  570. Some widgets can hold much data. (Currently only the edit widget
  571. capable to perform this action.)
  572.  
  573.    The `Save:' action will save the data found in the named widget to
  574. the filename found in `<output file>' attribute.
  575.  
  576.    FIXME: This function is not working now, need to be fixed.
  577.  
  578. 6.2.7 `Fileselect:WIDGET'
  579. -------------------------
  580.  
  581. 6.2.8 `Clear:WIDGET'
  582. --------------------
  583.  
  584. 6.2.9 `RemoveSelected:WIDGET'
  585. -----------------------------
  586.  
  587.  
  588. 
  589. Tag Table:
  590. Node: Top512
  591. Node: Getting Gtkdialog1459
  592. Node: Introduction2705
  593. Node: Invoking the Program3201
  594. Node: Widgets5857
  595. Node: Static label6885
  596. Node: Pushbutton7189
  597. Node: Pre-defined pushbuttons9046
  598. Node: Entry9641
  599. Node: Checkbox10571
  600. Node: Pixmap12263
  601. Node: Menus12912
  602. Node: Trees13720
  603. Node: Containers14702
  604. Node: Actions14814
  605. Node: Start and exit15502
  606. Node: Widget manipulation16861
  607. 
  608. End Tag Table
  609.