adime_dialogf man page on DragonFly

Man page or keyword search:  
man Server   44335 pages
apropos Keyword Search (all sections)
Output format
DragonFly logo
[printable version]

adime_dialogf(3)	      Adime API Reference	      adime_dialogf(3)

NAME
       adime_dialogf

SYNOPSIS
       #include <adime.h>

       int  adime_dialogf(const	 char *title, int x, y, w, const char *format,
       ...);

DESCRIPTION
       Displays a dialog letting the user  edit	 several  different  kinds  of
       data.   `title´	specifies  the caption of the dialog while `x´ and `y´
       specify the top left corner of the dialog. Alternatively, either `x´ or
       `y´  or both can be set to `ADIME_ALIGN_CENTRE´ or `ADIME_ALIGN_RIGHT´,
       in which case the dialog will be centred	 respectively  right  aligned.
       `w´ specifies the width of the input field. The total width of the dia‐
       log depends on this number, and on the length of the strings  given  to
       the dialog.

       The format string consists of one or more field descriptions, each fol‐
       lowed be exactly one format specifier. The field description is a  hint
       text used to help the user know what the field should contain. The for‐
       mat specifier is a percent sign, followed by an identifier, followed by
       a  pair	of  square  brackets (possibly with some extra options between
       (which I will refer to as "format modifier")) and can  be  any  of  the
       following:

       %bool[]

       A  check box, which can be either on or off. Next argument should be an
       `int *´, which will be set to 0 for off and 1 for on. Don´t  use	 other
       values!

       %greybool[]

       A  three-state  greyable check box. Next argument should be an `int *´,
       which will be set to 0 for off, 1 for on, or 2 for greyed.   Don´t  use
       other values!

       %double[x,y], %float[x,y],

       %int[x,y], %short[x,y], %char[x,y],

       %uint[x,y], %ushort[x,y], %uchar[x,y],

       A  number  in  the  given format (uchar, ushort and uint are unsigned).
       The number will be clamped to the interval `x´ to `y´, inclusive.   You
       may  omit  `x´  or  `y´ or both (but keep the comma!) to make it be the
       minimum respectively maximum for the data type. Next argument should be
       a pointer to the given data type.

       %pdouble[x,y], %pfloat[x,y],

       %pint[x,y], %pshort[x,y], %pchar[x,y],

       %puint[x,y], %pushort[x,y], %puchar[x,y],

       "Plain"	number formats: With the corresponding formats not prefixed by
       "p", the user can actually enter any mathematical expression, but these
       formats	disable	 that  feature so he can only enter numbers. Otherwise
       equal to their non-p-prefixed counterparts.

       %string[bytes]

       A string of length <= `bytes´ (in bytes). Next  argument	 should	 be  a
       `char *´ with room for at least the given number of characters.	Remem‐
       ber that the number of characters that fit in the string will  be  less
       if  you	use  Unicode.  With  UTF-8,  a character may be as long as six
       bytes, and with Unicode they are always 2 bytes.

       %filename[len,extension,title]

       A filename of length <= `len´. Next argument should be a `char *´  with
       room  for at least the given number of bytes (this really is bytes, not
       characters, and a UTF-8 string can have characters  that	 are  6	 bytes
       long,  so you should allocate six times as many bytes as you want char‐
       acters!). The user will be able to enter the  filename  as  a  text  or
       click a button to bring up a file selector. `extension´ is a semicolon-
       separated list of file extensions (ie in the format  "bmp;pcx;tga;foo")
       which  will  be accepted by the file selector. You may omit `extension´
       (but keep the commas!), meaning that all file formats will be accepted.
       `title´	is  the	 title	of the file selector dialog. You may also omit
       `title´ (but keep the commas!), meaning that the description  text  for
       this field will be used.

       %list[lines,list]

       The  user can select an element in a list of strings. `lines´ specifies
       the height, in lines, of the list box (this can be omitted to  let  the
       function calculate the height for you). `list´ is a semicolon-separated
       list of strings (if one or more strings needs to	 contain  a  semicolon
       (´;´)  or  an end bracket (´]´), the character can be escaped by a per‐
       cent sign (´%´)). Next argument should be an `int *´, which will be set
       to the index of the string.

       %vlist[lines]

       The  user can select an element in a list of strings. `lines´ specifies
       the height, in lines, of the list box (this can be omitted to  let  the
       function calculate the height for you). Next argument should be an `int
       *´, which will be set to the index of the selected string, and  then  a
       `char  **´  which  specifies the strings to choose among, then an `int´
       which tells how many strings the list contains.

       %datafile[lines,types]

       The user can select an element in an Allegro DATAFILE. You should  pass
       first  an  `int *´, which will be set to the index of the datafile that
       was selected, and then a `DATAFILE *´, which should be the datafile  to
       look  in. `lines´ specifies the height, in lines, of the list box (this
       can be omitted to let the  function  calculate  the  height  for	 you).
       `types´	is  a  semicolon-separated  list  of  datafile types. You must
       include all four characters in each type, so it could for example  look
       like this:

	  "%datafile[7,BMP ;RLE ;XCMP; CMP]"

       %wlist[lines,title,list]

       %wvlist[lines,title]

       %wdatafile[lines,title,types]

       Like  %list[],  %vlist[] and %datafile, but rather than having the list
       box in the window, a button will be displayed. When the user clicks the
       button, a new window with the actual list in (and with the given title)
       will be opened.

       %nothing[]

       No input data. Will only display the preceding description text as usu‐
       ally.  This  can	 be used if you want a section of the dialog to have a
       special header.

       %line[]

       No input data. Will only display the  preceding	description  text  (if
       there  is  any) as usually, and then a horizontal delimitor line.  Like
       %nothing[], this can be used if you want a section of the dialog to  be
       delimited from the rest of the dialog.

       %button[text]

       A  button  (with	 the  given text on) which calls your custom callback.
       Next argument should be a function pointer, pointing to a  function  of
       the type

	  int my_callback(DIALOG *d);

       This  will  be called when the user clicks the button. It will be given
       the dialog object representing the button. Its return value  is	a  bit
       special: If it is 0, then nothing happens. If it is ADIME_REDRAW (which
       is defined to be the smallest negative number), then the dialog will be
       redrawn.	 If it is any other positive number, then the dialog will exit
       with that return value not saving the results of the dialog (the	 usual
       behavior	 of a cancel button). If it is any other negative number, then
       the sign will be removed and the unsigned number returned, and the con‐
       tents  of  the  dialog will be saved (the usual behavior of the ok but‐
       ton).

       You are allowed to open a new dialog inside your callback, which may be
       a less messy and more flexible alternative to %dialogf[].

       %buttonrow[BUTTONS]

       One  or	more buttons in a horizontal row. These are displayed the same
       way as the OK and Cancel buttons (actually, the OK and  Cancel  buttons
       are  implemented by appending a %buttonrow[] to the end of the dialog).
       Next argument should be a function pointer, pointing to a  function  of
       the type:

	  int my_callback(DIALOG *d, int n);

       This  will  be  called with the dialog object for the clicked button as
       the first argument and the index of this button as  the	second	(i.e.,
       n=1  for	 the  first  button, n=2 for the second and so on). The return
       value works the same way as for %button[] (see above).

       The modifier (BUTTONS) is itself	 a  format  string,  consisting	 of  a
       comma-separated list of buttons. Each button begins with the text which
       will appear on the button. Then comes an	 optional  semicolon-separated
       list of shortcuts to this button. An example may help to clarify:

	  %buttonrow[OK;CTRL+O;ENTER,Cancel;ESC,Help;F1;ALT+H]

       This format will display four buttons: OK, Cancel and Help. The OK but‐
       ton has the shortcuts CTRL-O and	 ENTER.	 The  Cancel  button  has  the
       shortcut	 ESC.  The Help button has the shortcuts F1 and ALT-H.	Short‐
       cuts are specified in uppercase, with the state of shift, ctrl, alt etc
       preceding  the  key  to press. The key has the same name as the `KEY_*´
       macro defined by	 Allegro  (i.e.,  "ENTER"  for	`KEY_ENTER´,  "3"  for
       `KEY_3´ and "NUMLOCK" for `KEY_NUMLOCK´). The state consists of zero or
       more key shift flags separated by plus signs. The names	of  these  are
       the   same   as	 Allegro´s   `KB_*_FLAG´  macros  (i.e.,  "SHIFT"  for
       `KB_SHIFT_FLAG´ and "CAPSLOCK" for `KB_CAPSLOCK_FLAG´).	If  you	 write
       e.g.  CTRL+O,  it means that CTRL must be held down while pressing O in
       order to activate the shortcut, while it is optional to hold down other
       key  modifiers, e.g., SHIFT. If you don´t want the shortcut to be acti‐
       vated  when  SHIFT  is  down  (for  instance),  then  you   can	 write
       CTRL+-SHIFT+O, i.e., you precede the forbidden key with a minus sign.

       %dialogf[buttontext]

       A  button which opens another adime_dialogf() sub-dialog. Next argument
       should be the title of the dialog as a `char *´, followed by `x´,  `y´,
       `edit_w´	 as  `int´s  and then `format´ as a `char *´.  These arguments
       correspond to the arguments given to  `adime_dialogf()´.	 Depending  on
       what  `format´ contains, you then have to add more parameters which the
       sub-dialog will alter. `buttontext´ is the text which will be displayed
       on  the button which opens the sub-dialog. An example may help to clar‐
       ify:

	  adime_dialogf("My dialog",
			ADIME_ALIGN_CENTRE, ADIME_ALIGN_CENTRE, 200,
			"Open sub-dialog:%dialog[Click me!]",
			"My sub-dialog",
			ADIME_ALIGN_CENTRE, ADIME_ALIGN_CENTRE, 200,
			"Save in text format:%bool[]",
			&text_format);

       %vdialogf[buttontext]

       This is like %dialogf[], except that the `...´ arguments are  given  as
       an  `adime_va_list´  rather  than being expanded into the same argument
       list. (see also `adime_va_list´)

       %chain[]

       This is like an "inline" version of %vdialogf[]: You  should  pass  two
       arguments,  first a format string and then an `adime_va_list´. The dia‐
       log defined by this format string and `adime_va_list´ will be  inserted
       directly into this dialog. (See exchain.c for an example.)

       Any  special characters mentioned here can be escaped by placing a per‐
       cent sign (´%´) before it, e.g. if you need  a  literal	´]´  character
       somewhere  in the format string. The field description may contain new‐
       lines.

       Returns 1 if the user selected the OK button, and 2 if he selected  the
       Cancel  button. The `...´ parameters will be left untouched if the user
       clicked Cancel but they will change to the new values if he clicked OK.
       The initial values of the parameters will be taken as default values in
       the dialog objects.

       The debug library is very useful when you use  this  function:  It  can
       detect  almost  all  illegal  format strings. If it finds one, it shuts
       down the program with a traceback and writes a description of the error
       to the file allegro.log.

       An  example  may	 help  to clarify things (see also the programs in the
       examples directory):

	  char name_buffer[1024] = "";
	  int age = 20;
	  int shoe_size = 40;
	  int married = 0;
	  char filename_buffer[1024] = "";

	  adime_dialogf("Fill in personal data",
			ADIME_ALIGN_CENTRE, ADIME_ALIGN_CENTRE, 200,
			"Name%string[1024]"
			"Age (years)%int[0,150]"
			"%line"
			"Shoe size (Swedish units)%float[10,60]"
			"Married%bool[]"
			"Favourite text file%filename[1024,txt,Select a text file]",
			name_buffer,
			&age,
			&shoe_size,
			&married,
			filename_buffer);

SEE ALSO
       adime_init(3),	 adime_vdialogf(3),    adime_bmp(3),	adime_font(3),
       adime_va_list(3)

Adime				 version 2.2.1		      adime_dialogf(3)
[top]

List of man pages available for DragonFly

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net