widgets/ml_user_directory.h

   1 /* Monolith user directory widget.
   2  * - by Richard W.M. Jones <rich@annexia.org>
   3  *
   4  * This library is free software; you can redistribute it and/or
   5  * modify it under the terms of the GNU Library General Public
   6  * License as published by the Free Software Foundation; either
   7  * version 2 of the License, or (at your option) any later version.
   8  *
   9  * This library is distributed in the hope that it will be useful,
  10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  12  * Library General Public License for more details.
  13  *
  14  * You should have received a copy of the GNU Library General Public
  15  * License along with this library; if not, write to the Free
  16  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  17  *
  18  * $Id: ml_user_directory.h,v 1.2 2003/02/22 15:34:33 rich Exp $
  19  */
  20
  21 #ifndef ML_USER_DIRECTORY_H
  22 #define ML_USER_DIRECTORY_H
  23
  24 #include <pool.h>
  25
  26 #include "monolith.h"
  27 #include "ml_form.h"
  28
  29 struct ml_user_directory;
  30 typedef struct ml_user_directory *ml_user_directory;
  31
  32 /* Function: new_ml_user_directory - monolith user directory widget
  33  * Function: ml_user_directory_get_selection
  34  * Function: ml_user_directory_set_selection
  35  * Function: ml_user_directory_set_callback
  36  *
  37  * The user directory is a widget for picking a user on the system.
  38  * It is very primitive at the moment, but in the future will become
  39  * more advanced (able to cope with 100s-millions of people in the
  40  * directory) with search features and so on.
  41  *
  42  * The user directory supports picking single users only at the moment,
  43  * but we intend to extend it in future to support picking multiple
  44  * users.
  45  *
  46  * The user directory can be used either a form input or as a
  47  * standalone widget which works rather like a button.
  48  *
  49  * It requires the schema in @code{sql/ml_userdir_create.sql}.
  50  *
  51  * @code{new_ml_user_directory} creates a new user directory widget.
  52  * The @code{pool}, @code{session} and @code{conninfo} arguments point
  53  * to a pool for allocations, the current session and a database
  54  * connection string. The @code{form} argument may be either a form
  55  * object (see @ref{new_ml_form(3)}), or @code{NULL} if this widget is
  56  * not going to be used in a form. @code{userid} is the initially
  57  * selected user ID, or it may be @code{0} meaning that no user is
  58  * selected initially.
  59  *
  60  * @code{ml_user_directory_(get|set)_selection} reads or changes the
  61  * currently selected user ID.
  62  *
  63  * @code{ml_user_directory_set_callback} sets a function which is
  64  * called when the currently selected user is changed. Callbacks
  65  * should only be set when the widget is NOT in a form.
  66  *
  67  * When the widget is used in a form, then the currently selected user
  68  * ID is only available when the form is submitted (ie. in the form's
  69  * callback function). When the widget is not in a form, then you can
  70  * set a callback for the widget, and call
  71  * @code{ml_user_directory_get_selection} during this function.
  72  */
  73 extern ml_user_directory new_ml_user_directory (pool pool, ml_session session, const char *conninfo, ml_form form, int userid);
  74 extern int ml_user_directory_get_selection (ml_user_directory w);
  75 extern void ml_user_directory_set_selection (ml_user_directory w, int userid);
  76 extern void ml_user_directory_set_callback (ml_user_directory w, void (*fn) (ml_session, void *), ml_session session, void *data);
  77
  78 #endif /* ML_USER_DIRECTORY_H */